@udene/sdk
Version:
Udene Fraud Detection SDK for JavaScript
483 lines (395 loc) • 13.4 kB
Markdown
# @udene/sdk
A comprehensive fraud detection and security package for JavaScript applications.
## Installation
```sh
npm install @udene/sdk
# or
yarn add @udene/sdk
```
## Usage
### Basic Initialization
```javascript
// ES Modules
import { UdeneClient } from '@udene/sdk';
// CommonJS
// const { UdeneClient } = require('@udene/sdk');
// Initialize with API key
const client = new UdeneClient('your_api_key');
// Or initialize with configuration object
const client = new UdeneClient({
apiKey: 'your_api_key',
baseURL: 'https://api.udene.net/v1', // Optional custom API URL
maxRetries: 5, // Optional retry count (default: 3)
disableLogging: false, // Optional logging flag
logger: (message, error) => { // Optional custom logger
console.warn(`Custom log: ${message}`, error);
}
});
```
### Fraud Metrics
Get real-time fraud metrics for your application:
```javascript
async function getFraudMetrics() {
try {
const metrics = await client.getMetrics();
console.log(`Current risk score: ${metrics.riskScore}`);
console.log(`Active users: ${metrics.activeUsers}`);
console.log(`Alert count: ${metrics.alertCount}`);
console.log(`Model accuracy: ${metrics.accuracy}%`);
// Use metrics to update your dashboard or trigger alerts
if (metrics.riskScore > 75) {
triggerHighRiskAlert();
}
return metrics;
} catch (error) {
console.error('Failed to fetch metrics:', error);
}
}
```
### Track User Interactions
Monitor user behavior for suspicious patterns:
```javascript
async function trackUserLogin(userId, ipAddress, deviceInfo) {
try {
const result = await client.trackInteraction({
userId: userId,
action: 'login',
metadata: {
ipAddress: ipAddress,
deviceId: deviceInfo.id,
browser: deviceInfo.browser,
location: deviceInfo.location,
timestamp: new Date().toISOString()
}
});
console.log(`Interaction tracked with ID: ${result.transactionId}`);
return result;
} catch (error) {
console.error('Failed to track interaction:', error);
// Handle validation errors
if (error.message.includes('Invalid input')) {
// Show appropriate error to user
}
}
}
```
### Analyze Transactions
Detect fraudulent transactions in real-time:
```javascript
async function processPayment(userId, paymentDetails) {
try {
// First analyze the transaction for fraud
const analysis = await client.analyzeTransaction({
transactionId: paymentDetails.id,
userId: userId,
amount: paymentDetails.amount,
currency: paymentDetails.currency,
paymentMethod: paymentDetails.method,
timestamp: new Date().toISOString(),
metadata: {
productIds: paymentDetails.items.map(item => item.id),
shippingAddress: paymentDetails.shippingAddress,
billingAddress: paymentDetails.billingAddress,
isRecurring: paymentDetails.isSubscription
}
});
// Handle the result based on risk assessment
switch (analysis.recommendation) {
case 'approve':
return processApprovedPayment(paymentDetails);
case 'review':
flagForManualReview(paymentDetails, analysis.reasons);
return {
status: 'pending_review',
message: 'Your payment is being reviewed for security purposes.'
};
case 'deny':
logRejectedPayment(paymentDetails, analysis.reasons);
return {
status: 'rejected',
message: 'Payment could not be processed. Please contact support.'
};
}
} catch (error) {
console.error('Transaction analysis failed:', error);
throw new Error('Payment processing failed. Please try again.');
}
}
```
### Device Fingerprinting
Identify suspicious devices and prevent account takeovers:
```javascript
async function checkDeviceTrust() {
try {
const deviceInfo = await client.getDeviceFingerprint();
// Log device information
console.log(`Device ID: ${deviceInfo.deviceId}`);
console.log(`Browser: ${deviceInfo.browser}`);
console.log(`OS: ${deviceInfo.os}`);
console.log(`Trust score: ${deviceInfo.trustScore}`);
// Take action based on trust score
if (deviceInfo.trustScore < 30) {
// High risk device - require additional verification
return {
requiresVerification: true,
riskFactors: deviceInfo.riskFactors
};
}
return {
requiresVerification: false
};
} catch (error) {
console.error('Failed to get device fingerprint:', error);
// Fail open or closed depending on your security posture
return { requiresVerification: true, error: true };
}
}
```
### Activity Monitoring
Monitor suspicious activities across your platform:
```javascript
async function monitorActivity() {
try {
const activityData = await client.getActivity();
// Process suspicious activities
const suspiciousActivities = activityData.activities.filter(
activity => activity.type === 'suspicious'
);
if (suspiciousActivities.length > 0) {
console.warn(`Found ${suspiciousActivities.length} suspicious activities`);
// Take action on suspicious activities
suspiciousActivities.forEach(activity => {
logSecurityEvent({
id: activity.id,
description: activity.description,
timestamp: activity.timestamp
});
});
}
return activityData;
} catch (error) {
console.error('Failed to fetch activity data:', error);
}
}
```
## React Integration Example
```jsx
import React, { useEffect, useState } from 'react';
import { UdeneClient } from '@udene/sdk';
// Initialize the client outside component to avoid recreation on renders
const fraudClient = new UdeneClient('your_api_key');
function PaymentForm({ userId, amount, onComplete }) {
const [isProcessing, setIsProcessing] = useState(false);
const [error, setError] = useState(null);
const [requiresVerification, setRequiresVerification] = useState(false);
// Check device trust on component mount
useEffect(() => {
async function checkDevice() {
try {
const deviceCheck = await fraudClient.getDeviceFingerprint();
if (deviceCheck.trustScore < 40) {
setRequiresVerification(true);
}
// Track page view
await fraudClient.trackInteraction({
userId,
action: 'payment_page_view',
metadata: { amount }
});
} catch (err) {
console.error('Device check failed:', err);
}
}
checkDevice();
}, [userId, amount]);
const handleSubmit = async (e) => {
e.preventDefault();
setIsProcessing(true);
setError(null);
try {
// Get form data
const formData = new FormData(e.target);
const paymentMethod = formData.get('payment_method');
// Generate transaction ID
const transactionId = `txn_${Date.now()}`;
// Analyze transaction
const analysis = await fraudClient.analyzeTransaction({
transactionId,
userId,
amount: parseFloat(amount),
currency: 'USD',
paymentMethod,
timestamp: new Date().toISOString()
});
if (analysis.recommendation === 'approve') {
// Process payment
onComplete({ success: true, transactionId });
} else if (analysis.recommendation === 'review') {
setRequiresVerification(true);
setError('Additional verification required for this transaction.');
} else {
setError('This transaction cannot be processed. Please contact support.');
}
} catch (err) {
setError('Payment processing failed. Please try again.');
console.error('Payment error:', err);
} finally {
setIsProcessing(false);
}
};
return (
<div className="payment-form">
{requiresVerification && (
<div className="verification-notice">
For security reasons, additional verification is required.
<button onClick={() => /* Show verification UI */ null}>
Verify Identity
</button>
</div>
)}
<form onSubmit={handleSubmit}>
{/* Payment form fields */}
<select name="payment_method">
<option value="credit_card">Credit Card</option>
<option value="paypal">PayPal</option>
</select>
<button type="submit" disabled={isProcessing}>
{isProcessing ? 'Processing...' : `Pay $${amount}`}
</button>
{error && <div className="error-message">{error}</div>}
</form>
</div>
);
}
```
## API Reference
### UdeneClient
The main client for accessing fraud detection services.
#### Constructor
```javascript
new UdeneClient(apiKeyOrConfig, baseURL)
```
- `apiKeyOrConfig` (required) - Your API key as a string, or a configuration object
- `baseURL` (optional) - Custom API base URL if needed (ignored if config object is provided)
**Configuration Object Properties:**
```javascript
{
apiKey: 'your_api_key', // Required
baseURL: 'https://api.example.com', // Optional
maxRetries: 3, // Optional (default: 3)
disableLogging: false, // Optional (default: false)
logger: function(message, error) {} // Optional custom logger
}
```
#### Methods
| Method | Description | Parameters | Return Type |
|--------|-------------|------------|-------------|
| `getMetrics()` | Get fraud metrics for the current user/session | None | Promise\<MetricsResponse\> |
| `getActivity()` | Get activity data for analysis | None | Promise\<ActivityResponse\> |
| `trackInteraction(data)` | Track a user interaction for fraud analysis | TrackInteractionRequest | Promise\<TrackInteractionResponse\> |
| `analyzeTransaction(transaction)` | Analyze a transaction for fraud | TransactionAnalysisRequest | Promise\<TransactionAnalysisResponse\> |
| `getDeviceFingerprint()` | Get device fingerprint information | None | Promise\<DeviceFingerprintResponse\> |
#### Type Definitions
```typescript
// For TypeScript users, these interfaces are exported from the package
interface MetricsResponse {
riskScore: number;
activeUsers: number;
alertCount: number;
apiCalls: number;
accuracy: number;
falsePositiveRate: number;
avgProcessingTime: number;
concurrentCalls: number;
}
interface ActivityItem {
id: string;
type: 'suspicious' | 'normal';
description: string;
timestamp: string;
}
interface ActivityResponse {
activities: ActivityItem[];
}
interface TrackInteractionRequest {
userId: string;
action: string;
metadata?: Record<string, any>;
}
interface TrackInteractionResponse {
success: boolean;
transactionId: string;
}
interface TransactionAnalysisRequest {
transactionId: string;
userId: string;
amount?: number;
currency?: string;
paymentMethod?: string;
timestamp?: string;
metadata?: Record<string, any>;
}
interface TransactionAnalysisResponse {
riskScore: number;
recommendation: 'approve' | 'review' | 'deny';
reasons?: string[];
transactionId: string;
}
interface DeviceFingerprintResponse {
deviceId: string;
browser: string;
os: string;
ip: string;
location?: {
country?: string;
city?: string;
};
riskFactors?: string[];
trustScore?: number;
}
```
## Error Handling
The SDK includes built-in error handling with automatic retries for network issues and server errors (5xx). You can customize retry behavior and logging through the configuration options.
```javascript
try {
const result = await client.analyzeTransaction(data);
} catch (error) {
// Handle specific error types
if (error.message.includes('Invalid input')) {
// Handle validation errors
} else if (error.response && error.response.status === 429) {
// Handle rate limiting
console.log('Too many requests, please try again later');
} else {
// Handle other errors
console.error('Transaction analysis failed:', error);
}
}
```
## Advanced Usage
### Custom Retry Logic
The SDK automatically retries failed requests with exponential backoff for network errors and 5xx server responses. You can customize this behavior:
```javascript
const client = new UdeneClient({
apiKey: 'your_api_key',
maxRetries: 5, // Increase from default of 3
logger: (message, error) => {
// Custom retry logging
if (message.includes('Retrying request')) {
console.warn(message);
} else {
console.error(message, error);
}
}
});
```
### Disable Logging
For production environments, you might want to disable the default console logging:
```javascript
const client = new UdeneClient({
apiKey: 'your_api_key',
disableLogging: true
});
```
## License
MIT