@syeedalireza/auction-guard

A data-processing utility that analyzes bidding patterns to detect anomalies, fraud, and collusion in reverse auctions.

Architecture

classDiagram
    class AuctionGuard {
      +addStrategy(DetectionStrategy)
      +addBatchStrategy(BatchDetectionStrategy)
      +analyzeBid(bids, newBid)
      +analyzeBatch(bids)
    }
    class DetectionStrategy {
      <<interface>>
      +analyze(bids, newBid)
    }
    class BatchDetectionStrategy {
      <<interface>>
      +analyzeBatch(bids)
    }
    
    AuctionGuard --> DetectionStrategy
    AuctionGuard --> BatchDetectionStrategy
    
    DetectionStrategy <|-- RapidBiddingStrategy
    DetectionStrategy <|-- CollusionStrategy
    BatchDetectionStrategy <|-- HighVolumeBatchStrategy

Features

• Strategy Pattern: Easily extensible architecture to add new detection rules.
• Real-time Detection: Identifies bots or scripts placing too many bids in a short window (RapidBiddingStrategy) and alternating bid patterns (CollusionStrategy).
• Batch Processing: Supports heavy, periodic analysis of the entire auction history (HighVolumeBatchStrategy).
• Property-based Testing: Hardened against edge cases using fast-check.

Installation

npm install @syeedalireza/auction-guard lodash

Usage

import { 
  AuctionGuard, 
  RapidBiddingStrategy, 
  CollusionStrategy,
  HighVolumeBatchStrategy
} from '@syeedalireza/auction-guard';

// Initialize the guard
const guard = new AuctionGuard();

// Add real-time strategies
guard.addStrategy(new RapidBiddingStrategy(10, 60000)); // Max 10 bids per minute
guard.addStrategy(new CollusionStrategy(6, 300000)); // Look for 6 alternating bids in 5 mins

// Add batch strategies for cron jobs
guard.addBatchStrategy(new HighVolumeBatchStrategy(50)); // Max 50 bids per auction

// Current state of the auction
const existingBids = [
  // ... previous bids
];

// A new bid comes in
const newBid = {
  id: 'bid-123',
  bidderId: 'user-1',
  amount: 95,
  timestamp: Date.now()
};

// 1. Analyze in real-time
const realTimeReports = guard.analyzeBid(existingBids, newBid);

// 2. Analyze periodically (e.g., via a cron job)
const batchReports = guard.analyzeBatch([...existingBids, newBid]);

API

AuctionGuard

The main orchestrator.

• addStrategy(strategy: DetectionStrategy): void
• analyzeBid(bids: Bid[], newBid: Bid): AnomalyReport[]

RapidBiddingStrategy

Detects if a single user is bidding too frequently.

• constructor(maxBidsPerMinute: number = 10, timeWindowMs: number = 60000)

CollusionStrategy

Detects if two users are taking turns bidding to manipulate the timer or price.

• constructor(minSequenceLength: number = 6, timeWindowMs: number = 300000)

Types

interface Bid {
  id: string;
  bidderId: string;
  amount: number;
  timestamp: number;
}

interface AnomalyReport {
  isAnomalous: boolean;
  reason?: string;
  confidenceScore: number; // 0 to 1
}