Scam & Seller Profile APIs
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Scam & Seller Profile APIs provide the core intelligence for MarketSage's protective features. These interfaces allow the system to evaluate product listings for fraudulent characteristics and retrieve detailed trustworthiness metrics for sellers. By integrating keyword analysis, statistical price anomalies, and heuristic-based risk scoring, these APIs enable real-time security assessments for users browsing Chinese marketplaces.
The system is split between a lightweight backend implementation for rapid keyword-based detection and a sophisticated frontend/background service architecture that performs weighted multi-factor analysis.
Sources: development/backend/server.js, src/background/services/protect/securityAnalyzer.ts:1-20, development/frontend/index.html
API Architecture & Endpoints
The backend services are built using Express.js and utilize centralized middleware for rate limiting and error handling. The primary communication happens through RESTful endpoints that serve both the web MVP and the browser extension components.
Backend Endpoint Summary
| Endpoint | Method | Description | Data Parameters |
|---|---|---|---|
/api/scamDetection | POST | Analyzes text for scam keywords and returns probability. | { "text": string } |
/api/sellerProfile/:id | GET | Retrieves profile details for a specific seller. | sellerId (URL Param) |
Sources: development/backend/server.js:10-30, development/backend/routes/scamDetection.js:16-45, development/frontend/app.js:20-60
Scam Detection Logic (Backend)
The backend route provides a baseline analysis by filtering input strings against a predefined list of high-risk keywords including "scam", "fraud", "fake", "guarantee", and "urgent". The probability is calculated by normalizing the count of keyword matches against the total size of the keyword dictionary.
Advanced Security Analysis
While the backend provides basic keyword checks, the SecurityAnalyzer and ScamDetectionModel classes implement a multi-layered heuristic system. This system aggregates data from multiple specialized engines to produce a ScamAnalysisResult.
Security Metrics Model
The advanced analysis produces a SecurityMetrics object containing:
- Risk Score: A value from 0-100 representing overall threat.
- Warnings: An array of strings identifying specific risk factors.
- Seller Trust: A 0-100 score based on historical ratings.
Sources: src/background/services/protect/securityAnalyzer.ts:7-12
Weighted Heuristic Execution
The ScamDetectionModel coordinates several detection engines. Each heuristic is assigned a weight (0-1) and a score. The final probability is a weighted sum divided by the total weight of enabled heuristics.
| Heuristic ID | Source Engine | Purpose |
|---|---|---|
price_anomaly | AnomalyDetectionEngine | Checks if price deviates significantly from market average (Z-score). |
image_quality_analysis | ImageAnalysisEngine | Detects low quality or fraudulent product images. |
seller_history_analysis | SellerAnalysisEngine | Evaluates seller account age and listing volume. |
review_pattern_analysis | ReviewAnalyzer | Identifies review spikes or sentiment inconsistency. |
cross_platform_verification | CrossPlatformVerifier | Verifies listing consistency across different platforms. |
Sources: src/common/models/scamDetectionModel.ts:60-120, src/common/types/scamDetection.ts:3-11, src/common/models/scamDetection/reviewAnalyzer.ts:5-30
Risk Level Determination
The system maps the final probability (0.0 to 1.0) to four discrete risk levels:
- LOW: < 0.3
- MEDIUM: 0.3 - 0.6
- HIGH: 0.6 - 0.8
- CRITICAL: > 0.8
Sources: src/common/models/scamDetectionModel.ts:208-213
Data Flow & Integration
The following sequence shows how a user interaction triggers the analysis flow across the frontend and backend components.
Seller Profiling Logic
Seller profiles are evaluated based on historical data stored in the system. The SecurityAnalyzer calculates trust by normalizing ratings (0-5 scale) and checking for account maturity.
- Default Trust: New sellers without rating history receive a default trust score of 0.5.
- Rating Weighting: Recent ratings are weighted more heavily, and scores below 4.0 trigger specific security warnings.
- Anomalies: A high volume of listings on a new account (e.g., 15 days old) is flagged as a risk factor.
Sources: src/background/services/protect/securityAnalyzer.ts:53-60, src/background/services/protect/securityAnalyzer.ts:114-122, tests/unit/scamDetectionModel.test.ts:38-42
Conclusion
The Scam & Seller Profile APIs form a robust defensive layer for MarketSage. By combining simple string-based analysis for performance with complex, weighted heuristics for accuracy, the system provides users with actionable insights into the risks of online listings. The modular nature of the detection engines ensures that new threat patterns can be addressed by adding specialized heuristics without restructuring the core API.