@friendlycaptcha/server-sdk 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -17,6 +17,390 @@ declare const AUTH_REQUIRED = "auth_required";
  */
 declare const BAD_REQUEST = "bad_request";
 
+/**
+ * Automation and bot detection data.
+ *
+ * Available when the **Bot Detection** module is enabled.
+ * `null` when the **Bot Detection** module is not enabled.
+ *
+ * @summary Information about detected automation
+ * @public
+ */
+declare interface ClientAutomationData {
+    /**
+     * Whether the browser was detected as running in headless mode.
+     * @summary Headless browser detection
+     */
+    headless: boolean;
+    /**
+     * Detected automation tool information.
+     * @summary Automation tool detection results
+     */
+    automation_tool: ClientAutomationToolData;
+    /**
+     * Detected known bot information.
+     * @summary Known bot detection results
+     */
+    known_bot: ClientAutomationKnownBotData;
+}
+
+/**
+ * Known bot information. Known bots have public documentation about their identity and purpose, they are not
+ * trying to hide that they are bots. These are usually considered "good bots" depending on the use case.
+ *
+ * @summary Detected known bot details
+ * @public
+ */
+declare interface ClientAutomationKnownBotData {
+    /**
+     * Whether a known bot was detected.
+     * @summary Known bot detected flag
+     */
+    detected: boolean;
+    /**
+     * Bot identifier. Empty if no bot detected.
+     *
+     * @summary Bot ID
+     * @example "googlebot"
+     * @example "bingbot"
+     * @example "chatgpt"
+     */
+    id: string;
+    /**
+     * Human-readable bot name. Empty if no bot detected.
+     *
+     * @summary Bot name
+     * @example "Googlebot"
+     * @example "Bingbot"
+     * @example "ChatGPT"
+     */
+    name: string;
+    /**
+     * Bot type classification. Empty if no bot detected.
+     *
+     * @summary Type of bot
+     */
+    type: string;
+    /**
+     * Link to bot documentation. Empty if no bot detected.
+     *
+     * @summary URL with bot details
+     * @example "https://developers.google.com/search/docs/crawling-indexing/googlebot"
+     */
+    url: string;
+}
+
+/**
+ * Automation tool information.
+ * @summary Detected automation tool details
+ * @public
+ */
+declare interface ClientAutomationToolData {
+    /**
+     * Whether an automation tool was detected.
+     * @summary Automation tool detected flag
+     */
+    detected: boolean;
+    /**
+     * Automation tool identifier. Empty if no tool detected.
+     *
+     * @summary Tool ID
+     * @example "puppeteer"
+     * @example "selenium"
+     * @example "playwright"
+     * @example "webdriver"
+     */
+    id: string;
+    /**
+     * Human-readable tool name. Empty if no tool detected.
+     *
+     * @summary Tool name
+     * @example "Puppeteer"
+     * @example "Selenium"
+     * @example "Playwright"
+     * @example "WebDriver"
+     */
+    name: string;
+    /**
+     * Automation tool type. Empty if no tool detected.
+     *
+     * @summary Type of automation tool
+     */
+    type: string;
+}
+
+/**
+ * Detected browser information.
+ *
+ * Available when the **Browser Identification** module is enabled.
+ * `null` when the **Browser Identification** module is not enabled.
+ *
+ * @summary Detected browser details
+ * @public
+ */
+declare interface ClientBrowserData {
+    /**
+     * Unique browser identifier. Empty string if browser could not be identified.
+     *
+     * @summary Browser ID
+     * @example "firefox"
+     * @example "chrome"
+     * @example "chrome_android"
+     * @example "edge"
+     * @example "safari"
+     * @example "safari_ios"
+     * @example "webview_ios"
+     */
+    id: string;
+    /**
+     * Human-readable browser name. Empty string if browser could not be identified.
+     *
+     * @summary Browser name
+     * @example "Firefox"
+     * @example "Chrome"
+     * @example "Edge"
+     * @example "Safari"
+     * @example "Safari on iOS"
+     * @example "WebView on iOS"
+     */
+    name: string;
+    /**
+     * Browser version name. Assumed to be the most recent release matching the signature if exact version unknown. Empty if unknown.
+     *
+     * @summary Version number
+     * @example "146.0"
+     * @example "16.5"
+     */
+    version: string;
+    /**
+     * Release date of the browser version. In "YYYY-MM-DD" format. Empty string if unknown.
+     *
+     * @summary Browser version release date
+     * @example "2026-01-28"
+     */
+    release_date: string;
+}
+
+/**
+ * Browser engine (rendering engine) information.
+ *
+ * Available when the **Browser Identification** module is enabled.
+ * `null` when the **Browser Identification** module is not enabled.
+ *
+ * @summary Detected rendering engine details
+ * @public
+ */
+declare interface ClientBrowserEngineData {
+    /**
+     * Unique rendering engine identifier. Empty string if engine could not be identified.
+     *
+     * @summary Engine ID
+     * @example "gecko"
+     * @example "blink"
+     * @example "webkit"
+     */
+    id: string;
+    /**
+     * Human-readable engine name. Empty string if engine could not be identified.
+     *
+     * @summary Engine name
+     * @example "Gecko"
+     * @example "Blink"
+     * @example "WebKit"
+     */
+    name: string;
+    /**
+     * Rendering engine version. Assumed to be the most recent release matching the signature if exact version unknown. Empty if unknown.
+     *
+     * @summary Version number
+     * @example "146.0"
+     * @example "16.5"
+     */
+    version: string;
+}
+
+/**
+ * Client/device risk intelligence. Contains details about the client device, browser, operating system - in other words, the user agent.
+ *
+ * @summary Information about the user agent and device
+ * @public
+ */
+declare interface ClientData {
+    /**
+     * User-Agent HTTP header value.
+     * @summary User-Agent header
+     * @example "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:146.0) Gecko/20100101 Firefox/146.0"
+     */
+    header_user_agent: string;
+    /**
+     * Time zone information.
+     *
+     * Available when the **Browser Identification** module is enabled.
+     * `null` when the **Browser Identification** module is not enabled.
+     *
+     * @summary Browser time zone data
+     */
+    time_zone: ClientTimeZoneData | null;
+    /**
+     * Browser information.
+     *
+     * Available when the **Browser Identification** module is enabled.
+     * `null` when the **Browser Identification** module is not enabled.
+     *
+     * @summary Detected browser
+     */
+    browser: ClientBrowserData | null;
+    /**
+     * Browser engine information.
+     *
+     * Available when the **Browser Identification** module is enabled.
+     * `null` when the **Browser Identification** module is not enabled.
+     *
+     * @summary Detected rendering engine
+     */
+    browser_engine: ClientBrowserEngineData | null;
+    /**
+     * Device information.
+     *
+     * Available when the **Browser Identification** module is enabled.
+     * `null` when the **Browser Identification** module is not enabled.
+     *
+     * @summary Detected device
+     */
+    device: ClientDeviceData | null;
+    /**
+     * Operating system information.
+     *
+     * Available when the **Browser Identification** module is enabled.
+     * `null` when the **Browser Identification** module is not enabled.
+     *
+     * @summary Detected operating system
+     */
+    os: ClientOSData | null;
+    /**
+     * TLS signatures.
+     *
+     * Available when the **Bot Detection** module is enabled.
+     * `null` when the **Bot Detection** module is not enabled.
+     *
+     * @summary TLS signatures
+     */
+    tls_signature: TLSSignatureData | null;
+    /**
+     * Automation detection data. Contains information about what type of automation was recognized.
+     *
+     * Available when the **Bot Detection** module is enabled.
+     * `null` when the **Bot Detection** module is not enabled.
+     *
+     * @summary Bot and automation detection
+     */
+    automation: ClientAutomationData | null;
+}
+
+/**
+ * Device type and screen information.
+ *
+ * Available when the **Browser Identification** module is enabled.
+ * `null` when the **Browser Identification** module is not enabled.
+ *
+ * @summary Detected device details
+ * @public
+ */
+declare interface ClientDeviceData {
+    /**
+     * Device type.
+     * @summary Type of device
+     * @example "desktop"
+     * @example "mobile"
+     * @example "tablet"
+     */
+    type: string;
+    /**
+     * Device brand.
+     * @summary Manufacturer brand
+     * @example "Apple"
+     * @example "Samsung"
+     * @example "Google"
+     */
+    brand: string;
+    /**
+     * Device model.
+     * @summary Device model name
+     * @example "iPhone 17"
+     * @example "Galaxy S21 (SM-G991B)"
+     * @example "Pixel 10"
+     */
+    model: string;
+}
+
+/**
+ * Operating system information.
+ *
+ * Available when the Browser Identification module is enabled.
+ * `null` when the Browser Identification module is not enabled.
+ *
+ * @summary Detected OS details
+ * @public
+ */
+declare interface ClientOSData {
+    /**
+     * Unique operating system identifier. "unknown" if OS could not be identified.
+     *
+     * @summary OS ID
+     * @example "windows"
+     * @example "macos"
+     * @example "ios"
+     * @example "android"
+     * @example "linux"
+     */
+    id: string;
+    /**
+     * Human-readable operating system name. Empty string if OS could not be identified.
+     *
+     * @summary OS name
+     * @example "Windows"
+     * @example "macOS"
+     * @example "iOS"
+     * @example "Android"
+     * @example "Linux"
+     */
+    name: string;
+    /**
+     * Operating system version.
+     * @summary Version number
+     * @example "10"
+     * @example "11.2.3"
+     * @example "14.4"
+     */
+    version: string;
+}
+
+/**
+ * Time zone information from the browser.
+ *
+ * Available when the **Browser Identification** module is enabled.
+ * `null` when the **Browser Identification** module is not enabled.
+ *
+ * @summary IANA time zone data
+ * @public
+ */
+declare interface ClientTimeZoneData {
+    /**
+     * IANA time zone name reported by the browser.
+     * @summary IANA time zone identifier
+     * @example "America/New_York" or "Europe/Berlin"
+     */
+    name: string;
+    /**
+     * Two-letter ISO 3166-1 alpha-2 country code derived from the time zone.
+     * "XU" if timezone is missing or cannot be mapped to a country (e.g., "Etc/UTC").
+     *
+     * @summary Country derived from time zone
+     * @example "US" or "DE"
+     */
+    country_iso2: string;
+}
+
 /**
  * An error occured on the client side that could've been prevented. This generally means your configuration is wrong.
  *
@@ -50,6 +434,11 @@ export declare class FriendlyCaptchaClient {
     private strict;
     private fetch;
     constructor(opts: FriendlyCaptchaOptions);
+    /**
+     * Get the siteverify endpoint URL being used by this client.
+     * @internal - For testing purposes only
+     */
+    getSiteverifyEndpoint(): string;
     /**
      * Verify a captcha response.
      *
@@ -76,7 +465,17 @@ export declare interface FriendlyCaptchaOptions {
      */
     apiKey: string;
     /**
+     * The API endpoint domain to use. Can be "eu", "global", or a custom domain (e.g., "https://api.example.com").
+     * Do not include a path - it will be automatically appended.
+     *
+     * Defaults to `"global"`.
+     */
+    apiEndpoint?: string;
+    /**
+     * @deprecated Use `apiEndpoint` instead. This option will be removed in a future version.
+     *
      * The endpoint to use for the API. Can be "eu", "global", or a custom URL.
+     * If a full URL with a path is provided, the path will be stripped.
      *
      * Defaults to `"global"`.
      */
@@ -100,6 +499,290 @@ export declare interface FriendlyCaptchaOptions {
  */
 declare const INTERNAL_SERVER_ERROR = "internal_server_error";
 
+/**
+ * Abuse contact information for reporting network abuse.
+ *
+ * Available when the **IP Intelligence** module is enabled.
+ * `null` when the **IP Intelligence** module is not enabled.
+ *
+ * @summary Contact details for reporting abuse
+ * @public
+ */
+declare interface NetworkAbuseContactData {
+    /**
+     * Postal address of the abuse contact.
+     * @summary Abuse contact postal address
+     * @example "Vodafone GmbH, Campus Eschborn, Duesseldorfer Strasse 15, D-65760 Eschborn, Germany"
+     */
+    address: string;
+    /**
+     * Name of the abuse contact person or team.
+     * @summary Abuse contact name
+     * @example "Vodafone Germany IP Core Backbone"
+     */
+    name: string;
+    /**
+     * Abuse contact email address.
+     * @summary Email for abuse reports
+     * @example "abuse.de@vodafone.com"
+     */
+    email: string;
+    /**
+     * Abuse contact phone number.
+     * @summary Phone for abuse reports
+     * @example "+49 6196 52352105"
+     */
+    phone: string;
+}
+
+/**
+ * IP anonymization and privacy information.
+ *
+ * Available when the **Anonymization Detection** module is enabled.
+ * `null` when the **Anonymization Detection** module is not enabled.
+ *
+ * @summary Detection of VPNs, proxies, and anonymization services
+ * @public
+ */
+declare interface NetworkAnonymizationData {
+    /**
+     * Likelihood that the IP is from a VPN service.
+     * @summary VPN detection score
+     */
+    vpn_score: RiskScore;
+    /**
+     * Likelihood that the IP is from a proxy service.
+     * @summary Proxy detection score
+     */
+    proxy_score: RiskScore;
+    /**
+     * Whether the IP is a Tor exit node.
+     * @summary Tor exit node detection
+     */
+    tor: boolean;
+    /**
+     * Whether the IP is from iCloud Private Relay.
+     * @summary iCloud Private Relay detection
+     * @see https://support.apple.com/en-us/102602
+     */
+    icloud_private_relay: boolean;
+}
+
+/**
+ * Autonomous System (AS) information.
+ *
+ * Available when the **IP Intelligence** module is enabled for your account.
+ * `null` when the **IP Intelligence** module is not enabled for your account.
+ *
+ * @summary Information about the AS that owns the IP
+ * @public
+ */
+declare interface NetworkAutonomousSystemData {
+    /**
+     * Autonomous System Number (ASN) identifier.
+     * @summary Autonomous System Number (ASN).
+     * @example 3209 for Vodafone GmbH
+     */
+    number: number;
+    /**
+     * Name of the autonomous system. This is usually a short name or handle.
+     * @summary AS name
+     * @example "VODANET"
+     */
+    name: string;
+    /**
+     * Organization name that owns the ASN.
+     * @summary Company that owns the AS
+     * @example "Vodafone GmbH"
+     */
+    company: string;
+    /**
+     * Description of the company that owns the ASN.
+     * @summary Short description of the company
+     * @example "Provides mobile and fixed broadband and telecommunication services to consumers and businesses."
+     */
+    description: string;
+    /**
+     * Domain name associated with the ASN.
+     * @summary Company domain
+     * @example "vodafone.de"
+     */
+    domain: string;
+    /**
+     * Two-letter ISO 3166-1 alpha-2 country code where the ASN is registered.
+     * @summary ASN registration country
+     * @example "DE"
+     */
+    country: string;
+    /**
+     * Regional Internet Registry that allocated the ASN.
+     * @summary RIR that allocated this ASN
+     * @example "RIPE"
+     */
+    rir: string;
+    /**
+     * IP route associated with the ASN.
+     * @summary IP route in CIDR notation
+     * @example "88.64.0.0/12"
+     */
+    route: string;
+    /**
+     * Type of the autonomous system.
+     * @summary AS type classification
+     * @example "isp"
+     */
+    type: string;
+}
+
+/**
+ * Network-related risk intelligence.
+ * @summary Information about the network
+ * @public
+ */
+declare interface NetworkData {
+    /**
+     * IP address used when requesting the challenge.
+     * @summary Client IP address
+     * @example "88.64.4.22"
+     */
+    ip: string;
+    /**
+     * Autonomous System information.
+     *
+     * Available when the **IP Intelligence** module is enabled.
+     * `null` when the **IP Intelligence** module is not enabled.
+     *
+     * @summary AS data for the IP
+     */
+    as: NetworkAutonomousSystemData | null;
+    /**
+     * Geolocation information.
+     *
+     * Available when the **IP Intelligence** module is enabled.
+     * `null` when the **IP Intelligence** module is not enabled.
+     *
+     * @summary Geographic location of the IP
+     */
+    geolocation: NetworkGeolocationData | null;
+    /**
+     * Abuse contact information.
+     *
+     * Available when the **IP Intelligence** module is enabled.
+     * `null` when the **IP Intelligence** module is not enabled.
+     *
+     * @summary Contact for abuse reports
+     */
+    abuse_contact: NetworkAbuseContactData | null;
+    /**
+     * IP masking/anonymization information.
+     *
+     * Available when the **Anonymization Detection** module is enabled.
+     * `null` when the **Anonymization Detection** module is not enabled.
+     *
+     * @summary VPN, proxy, and Tor detection
+     */
+    anonymization: NetworkAnonymizationData | null;
+}
+
+/**
+ * Country information.
+ * @summary Detailed country data
+ * @public
+ */
+declare interface NetworkGeolocationCountryData {
+    /**
+     * Two-letter ISO 3166-1 alpha-2 country code.
+     * @summary ISO 3166-1 alpha-2 code
+     * @example "DE"
+     */
+    iso2: string;
+    /**
+     * Three-letter ISO 3166-1 alpha-3 country code.
+     * @summary ISO 3166-1 alpha-3 code
+     * @example "DEU"
+     */
+    iso3: string;
+    /**
+     * English name of the country.
+     * @summary Country name in English
+     * @example "Germany"
+     */
+    name: string;
+    /**
+     * Native name of the country.
+     * @summary Country name in native language
+     * @example "Deutschland"
+     */
+    name_native: string;
+    /**
+     * Geographic region.
+     * @summary Major world region
+     * @example "Europe"
+     */
+    region: string;
+    /**
+     * Geographic subregion.
+     * @summary More specific world region
+     * @example "Western Europe"
+     */
+    subregion: string;
+    /**
+     * Currency code.
+     * @summary ISO 4217 currency code
+     * @example "EUR"
+     */
+    currency: string;
+    /**
+     * Currency name.
+     * @summary Full name of the currency
+     * @example "Euro"
+     */
+    currency_name: string;
+    /**
+     * International dialing code.
+     * @summary Country phone code
+     * @example "49"
+     */
+    phone_code: string;
+    /**
+     * Capital city.
+     * @summary Name of the capital city
+     * @example "Berlin"
+     */
+    capital: string;
+}
+
+/**
+ * Geolocation information for the IP address.
+ *
+ * Available when the **IP Intelligence** module is enabled.
+ * `null` when the **IP Intelligence** module is not enabled.
+ *
+ * @summary Geographic location of the IP address
+ * @public
+ */
+declare interface NetworkGeolocationData {
+    /**
+     * Country information.
+     * @summary Detailed country data
+     */
+    country: NetworkGeolocationCountryData;
+    /**
+     * City name. Empty string if unknown.
+     *
+     * @summary City of the IP address
+     * @example "Eschborn"
+     */
+    city: string;
+    /**
+     * State, region, or province. Empty string if unknown.
+     *
+     * @summary State/region/province of the IP address
+     * @example "Hessen"
+     */
+    state: string;
+}
+
 /**
  *
  * The request couldn't be made, perhaps there is a network outage, DNS issue, or the API is unreachable.
@@ -144,6 +827,110 @@ declare const RESPONSE_MISSING = "response_missing";
  */
 declare const RESPONSE_TIMEOUT = "response_timeout";
 
+/** @summary High risk score (4/5)
+ *  @public
+ */
+declare const RISK_SCORE_HIGH: 4;
+
+/** @summary Low risk score (2/5)
+ *  @public
+ */
+declare const RISK_SCORE_LOW: 2;
+
+/** @summary Medium risk score (3/5)
+ *  @public
+ */
+declare const RISK_SCORE_MEDIUM: 3;
+
+/** @summary Unknown or missing risk score
+ *  @public
+ */
+declare const RISK_SCORE_UNKNOWN: 0;
+
+/** @summary Very high risk score (5/5)
+ *  @public
+ */
+declare const RISK_SCORE_VERY_HIGH: 5;
+
+/** @summary Very low risk score (1/5)
+ *  @public
+ */
+declare const RISK_SCORE_VERY_LOW: 1;
+
+/**
+ * Risk intelligence data. Contains risk scores, network data, and client data. Field availability depends on enabled modules.
+ *
+ * @summary All risk intelligence information
+ * @public
+ */
+declare interface RiskIntelligenceData {
+    /**
+     * Risk scores from various signals, these summarize the risk intelligence assessment.
+     *
+     * Available when the **Risk Scores** module is enabled.
+     * `null` when the **Risk Scores** module is not enabled.
+     *
+     * @summary Calculated risk scores
+     */
+    risk_scores: RiskScoresData | null;
+    /**
+     * Network-related risk intelligence.
+     * @summary Network and IP information
+     */
+    network: NetworkData;
+    /**
+     * Client/device risk intelligence.
+     * @summary User agent and device information
+     */
+    client: ClientData;
+}
+
+/**
+ * Risk score value ranging from 1 to 5.
+ * - 0: Unknown or missing
+ * - 1: Very low risk
+ * - 2: Low risk
+ * - 3: Medium risk
+ * - 4: High risk
+ * - 5: Very high risk
+ *
+ * @summary Risk score indicating likelihood of malicious activity
+ * @public
+ */
+declare type RiskScore = typeof RISK_SCORE_UNKNOWN | typeof RISK_SCORE_VERY_LOW | typeof RISK_SCORE_LOW | typeof RISK_SCORE_MEDIUM | typeof RISK_SCORE_HIGH | typeof RISK_SCORE_VERY_HIGH;
+
+/**
+ * Risk scores summarize the entire risk intelligence assessment into scores per category.
+ *
+ * Available when the **Risk Scores** module is enabled for your account.
+ * `null` when the **Risk Scores** module is not enabled for your account.
+ *
+ * @summary Risk scores for different categories
+ * @public
+ */
+declare interface RiskScoresData {
+    /**
+     * Overall risk score combining all signals.
+     *
+     * @summary Overall risk score
+     */
+    overall: RiskScore;
+    /**
+     * Network-related risk score. Captures likelihood of automation/malicious activity based on
+     * IP address, ASN, reputation, geolocation, past abuse from this network, and other network signals.
+     *
+     * @summary Risk score based on network signals
+     */
+    network: RiskScore;
+    /**
+     * Browser-related risk score. Captures likelihood of automation, malicious activity or browser spoofing based on
+     * user agent consistency, automation traces, past abuse, and browser characteristics.
+     *
+     * @summary Risk score based on browser signals
+     */
+    browser: RiskScore;
+}
+
 /**
  * The sitekey in your request is invalid.
  *
@@ -207,7 +994,18 @@ export declare interface SiteverifyResponseChallengeData {
  * @public
  */
 export declare interface SiteverifyResponseData {
+    /**
+     * EventID is unique for this siteverify request.
+     */
+    event_id: string;
+    /**
+     * Challenge data contains information about the captcha challenge that was completed, such as the timestamp and origin.
+     */
     challenge: SiteverifyResponseChallengeData;
+    /**
+     * Risk intelligence data contains information about the client that completed the captcha challenge, such as the browser, operating system, and any detected automation tools or bots. This is only included if the Risk Intelligence module is enabled for your account.
+     */
+    risk_intelligence: RiskIntelligenceData | null;
 }
 
 /**
@@ -218,6 +1016,37 @@ export declare interface SiteverifySuccessResponse {
     data: SiteverifyResponseData;
 }
 
+/**
+ * TLS/SSL signatures, sometimes also called TLS fingerprints. These are derived from the TLS handshake
+ * between the client and server, specifically the Client Hello message sent by the client.
+ *
+ * Available when the **Bot Detection** module is enabled.
+ * `null` when the **Bot Detection** module is not enabled.
+ *
+ * @summary TLS client hello signatures
+ * @public
+ */
+declare interface TLSSignatureData {
+    /**
+     * JA3 hash.
+     * @summary JA3 TLS signature
+     * @example "d87a30a5782a73a83c1544bb06332780"
+     */
+    ja3: string;
+    /**
+     * JA3N hash.
+     * @summary JA3N TLS signature
+     * @example "28ecc2d2875b345cecbb632b12d8c1e0"
+     */
+    ja3n: string;
+    /**
+     * JA4 signature.
+     * @summary JA4 TLS signature
+     * @example "t13d1516h2_8daaf6152771_02713d6af862"
+     */
+    ja4: string;
+}
+
 /**
  * @public
  */