fraud-check-ts

A powerful TypeScript library for IP address fraud detection and validation. Integrate IP-API service to analyze IP addresses and determine their potential for fraudulent activity based on geographic location, proxy detection, hosting detection, and customizable rules.

🚀 Features

• ✅ IP Validation - Validate IPv4 and IPv6 addresses
• 🌍 Country Filtering - Whitelist or blacklist countries
• 🔒 Proxy Detection - Detect and optionally allow specific proxy services
• 🏢 Hosting Detection - Identify datacenter/hosting IPs
• 🛡️ Privacy Service Bypass - Optionally allow iCloud Private Relay, Cloudflare WARP
• 🎯 Custom Relay Bypass - Whitelist specific VPN/proxy organizations
• 📊 TypeScript Support - Full type safety and IntelliSense
• ⚡ Lightweight - Minimal dependencies
• 🧪 Well Tested - Comprehensive test coverage

📦 Installation

npm install fraud-check-ts

yarn add fraud-check-ts

pnpm add fraud-check-ts

🔑 API Key (Optional)

This package uses the IP-API service. The free tier allows 45 requests per minute. For higher limits, get a pro API key from IP-API Pro.

📖 Quick Start

import { FraudChecker } from "fraud-check-ts";

// Create an instance (optional API key for pro tier)
const checker = new FraudChecker({
  key: "your-api-key", // Optional, remove for free tier
});

// Verify an IP address
const result = await checker.verify("8.8.8.8", {
  validCountries: ["US", "GB", "CA"],
});

if (result.success) {
  console.log("✅ IP passed validation");
} else {
  console.log("❌ IP failed:", result.reason);
}

📚 API Documentation

Constructor

new FraudChecker(options)

Creates a new FraudChecker instance.

Parameters:

• options.key (optional): API key for IP-API Pro tier

Example:

// Free tier
const checker = new FraudChecker({});

// Pro tier with API key
const checker = new FraudChecker({
  key: "your-pro-api-key",
});

Methods

verify(ip: string, options: VerifyOptions): Promise<VerifyResponse>

Verifies an IP address against your specified rules.

Returns:

// Success
{ success: true }

// Failure
{
  success: false,
  reason: "invalid_ip" | "status_fail" | "is_proxy" | "is_hosting" |
          "banned_country" | "not_valid_country" | string
}

🎯 Verification Options

Country Filtering

Option 1: Valid Countries (Whitelist)

Allow only specific countries.

const result = await checker.verify("8.8.8.8", {
  validCountries: ["US", "GB", "CA", "AU"],
});

Use case: E-commerce site only serving specific markets

Option 2: Banned Countries (Blacklist)

Block specific countries, allow all others.

const result = await checker.verify("203.0.113.0", {
  bannedCountries: ["CN", "RU", "KP"],
});

Use case: Block high-risk regions while serving globally

Proxy Detection

allowProxy: boolean

Allow or block all proxy connections.

// Block all proxies (default behavior)
const result = await checker.verify("1.2.3.4", {
  validCountries: ["US"],
  allowProxy: false, // or omit this line
});

// Allow all proxies
const result = await checker.verify("1.2.3.4", {
  validCountries: ["US"],
  allowProxy: true,
});

Use case: Strict fraud prevention vs. accessibility

byPassIcloudRelay: boolean

Allow iCloud Private Relay while blocking other proxies.

const result = await checker.verify("17.253.144.10", {
  validCountries: ["US"],
  allowProxy: false,
  byPassIcloudRelay: true, // ✅ Allow iCloud Private Relay
});

Use case: Support privacy-conscious Apple users

byPassCloudflareWarp: boolean

Allow Cloudflare WARP while blocking other proxies.

const result = await checker.verify("1.1.1.1", {
  validCountries: ["US"],
  allowProxy: false,
  byPassCloudflareWarp: true, // ✅ Allow Cloudflare WARP
});

Use case: Support users with Cloudflare's privacy service

byPassCustomRelay: string[]

Allow specific VPN/proxy services by organization name.

const result = await checker.verify("some-ip", {
  validCountries: ["US"],
  allowProxy: false,
  byPassCustomRelay: [
    "NordVPN",
    "ProtonVPN",
    "Corporate VPN",
    "My Company Inc",
  ],
});

Use case: Whitelist trusted VPN services or corporate networks

Finding Organization Names:

curl "http://ip-api.com/json/YOUR_IP?fields=org"

Hosting Detection

allowHosting: boolean

Allow or block datacenter/hosting IPs.

// Block hosting IPs (AWS, Azure, etc.)
const result = await checker.verify("54.123.45.67", {
  validCountries: ["US"],
  allowHosting: false,
});

// Allow hosting IPs
const result = await checker.verify("54.123.45.67", {
  validCountries: ["US"],
  allowHosting: true,
});

Use case: Prevent bot traffic from cloud providers

API Failure Handling

allowFailStatus: boolean

Handle cases where IP-API cannot determine the IP info.

const result = await checker.verify("invalid-ip", {
  validCountries: ["US"],
  allowFailStatus: true, // ✅ Don't fail on API errors
});

Use case: Graceful degradation when API is unavailable

🏭 Factory Functions

Alternative ways to create instances:

import { fraudChecker, FraudChecker } from "fraud-check-ts";

// Method 1: Factory function
const checker1 = fraudChecker({ key: "your-key" });

// Method 2: Static method
const checker2 = FraudChecker.fraudChecker({ key: "your-key" });

// Method 3: Constructor (recommended)
const checker3 = new FraudChecker({ key: "your-key" });

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

ISC License - see LICENSE file for details

🔗 Links

• IP-API Documentation
• GitHub Repository
• npm Package
• Report Issues

💬 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki

Made with ❤️ by FahDev.