fraud-check-ts
Version:
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.
286 lines (198 loc) • 6.84 kB
Markdown
# fraud-check-ts
[](https://www.npmjs.com/package/fraud-check-ts)
[](https://opensource.org/licenses/ISC)
[](https://www.typescriptlang.org/)
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
```bash
npm install fraud-check-ts
```
```bash
yarn add fraud-check-ts
```
```bash
pnpm add fraud-check-ts
```
## 🔑 API Key (Optional)
This package uses the [IP-API](https://ip-api.com/) service. The free tier allows 45 requests per minute. For higher limits, get a pro API key from [IP-API Pro](https://members.ip-api.com/).
## 📖 Quick Start
```typescript
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:**
```typescript
// 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:**
```typescript
// 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.
```typescript
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.
```typescript
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.
```typescript
// 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.
```typescript
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.
```typescript
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.
```typescript
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:**
```bash
curl "http://ip-api.com/json/YOUR_IP?fields=org"
```
### Hosting Detection
#### `allowHosting: boolean`
Allow or block datacenter/hosting IPs.
```typescript
// 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.
```typescript
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:
```typescript
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](LICENSE) file for details
## 🔗 Links
- [IP-API Documentation](https://ip-api.com/docs)
- [GitHub Repository](https://github.com/LokiWasHere/fraud-check-ts)
- [npm Package](https://www.npmjs.com/package/fraud-check-ts)
- [Report Issues](https://github.com/LokiWasHere/fraud-check-ts/issues)
## 💬 Support
- 📧 Email: your@email.com
- 🐛 Issues: [GitHub Issues](https://github.com/LokiWasHere/fraud-check-ts/issues)
- 📖 Documentation: [GitHub Wiki](https://github.com/LokiWasHere/fraud-check-ts/wiki)
---
Made with ❤️ by FahDev.