fraud-check-ts/dist/index.d.ts

A powerful TypeScript library for IP address fraud detection and validation. Detect proxies, VPNs, hosting IPs, and filter by country with support for custom whitelist rules.

/**
 * Failure reason types for IP verification
 */
type FailureReason = "invalid_ip" | "status_fail" | "is_proxy" | "is_hosting" | "banned_country" | "not_valid_country";
/**
 * IP-API response when the request fails
 */
type IpApiFailResponse = {
    status: "fail";
    countryCode: undefined;
    org: undefined;
    proxy: undefined;
    hosting: undefined;
};
/**
 * IP-API response when the request succeeds
 */
type IpApiSuccessResponse = {
    status: "success";
    countryCode: string;
    org: "iCloud Private Relay" | "Cloudflare WARP" | string;
    proxy: boolean;
    hosting: boolean;
};
/**
 * Union type for IP-API responses
 */
type IpApiResponse = IpApiFailResponse | IpApiSuccessResponse;
/**
 * Constructor options for FraudChecker
 */
type ConstructorType = {
    key?: string;
};
/**
 * Options for verifying an IP address
 */
type VerifyOptions = ({
    validCountries: string[];
} | {
    bannedCountries: string[];
}) & {
    allowProxy?: boolean;
    allowHosting?: boolean;
    allowFailStatus?: boolean;
    byPassIcloudRelay?: boolean;
    byPassCloudflareWarp?: boolean;
    byPassCustomRelay?: string[];
};
/**
 * Successful verification response
 */
type VerifySuccessResponse = {
    success: true;
};
/**
 * Failed verification response
 */
type VerifyFailureResponse = {
    success: false;
    reason: FailureReason | string;
};
/**
 * Union type for verification responses
 */
type VerifyResponse = VerifySuccessResponse | VerifyFailureResponse;

/**
 * FraudChecker class for validating IP addresses against fraud criteria
 */
declare class FraudChecker {
    readonly key: string | undefined;
    constructor(payload: ConstructorType);
    /**
     * Verifies an IP address against the provided options
     * @param ip - The IP address to verify
     * @param opts - Verification options including country filters and flags
     * @returns Promise resolving to verification result
     */
    verify(ip: string, opts: VerifyOptions): Promise<VerifyResponse>;
    /**
     * Static factory method to create a FraudChecker instance
     * @param payload - Constructor options
     * @returns New FraudChecker instance
     */
    static fraudChecker(payload: ConstructorType): FraudChecker;
}

/**
 * Factory function to create a FraudChecker instance
 * @param payload - Constructor options
 * @returns New FraudChecker instance
 */
declare function fraudChecker(payload: ConstructorType): FraudChecker;

/**
 * Validates if a string is a valid IPv4 or IPv6 address
 * @param ip - The IP address string to validate
 * @returns true if the IP is valid, false otherwise
 */
declare function isValidIp(ip: string): boolean;

export { type ConstructorType, type FailureReason, FraudChecker, type IpApiFailResponse, type IpApiResponse, type IpApiSuccessResponse, type VerifyFailureResponse, type VerifyOptions, type VerifyResponse, type VerifySuccessResponse, FraudChecker as default, fraudChecker, isValidIp };