{"_id":"@bolu1/fraud-guard","_rev":"2-6eecad0378d3f1b27142af381696d794","name":"@bolu1/fraud-guard","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bolu1/fraud-guard","version":"1.0.0","keywords":["fraud","fraud-detection","payment-fraud","anomaly-detection","machine-learning","risk-scoring","chargeback-prevention","transaction-monitoring","velocity-checks","payment-security","ecommerce","fintech","typescript","self-hosted","ai","tensorflow","cnn","fraud-prevention","risk-assessment","behavioral-analysis"],"author":{"name":"Bolu boluadetifa@gmail.com"},"license":"MIT","_id":"@bolu1/fraud-guard@1.0.0","maintainers":[{"name":"bolu1","email":"boluadetifa@gmail.com"}],"homepage":"https://github.com/bolu1/fraud-guard#readme","bugs":{"url":"https://github.com/bolu1/fraud-guard/issues"},"bin":{"fraud-guard":"dist/cli/index.js"},"dist":{"shasum":"50effec2b99f4cae0434b555a5b096068e9b474b","tarball":"https://registry.npmjs.org/@bolu1/fraud-guard/-/fraud-guard-1.0.0.tgz","fileCount":149,"integrity":"sha512-KXJym3fI4A0B1CRzDRtFCnGLz3wa6s12wf7wDf9KO5m2D9PdzYwYGkjf0toDBSBBRHPkmIjWQzM5F/wxRNTXZg==","signatures":[{"sig":"MEQCIHaIpISGLW/8xamnz+TZVKdGpxQw2FlLU+CRn88MntRoAiAQQ8HyzIrugLYtu0CtIVv/yC+e+axB1q2czvInQRg1Sg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":395525},"main":"./dist/index.js","type":"commonjs","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"e9796df77065af639db04be0e05a29faf68106ec","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","test":"jest","build":"tsc","clean":"rm -rf dist","format":"prettier --write \"src/**/*.ts\"","lint:fix":"eslint src --ext .ts --fix","test:watch":"jest --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"bolu1","email":"boluadetifa@gmail.com"},"repository":{"url":"git+https://github.com/bolu1/fraud-guard.git","type":"git"},"_npmVersion":"11.4.1","description":"An on-premise fraud detection package for Node.js applications with incremental learning for it's AI model and velocity checks.","directories":{},"_nodeVersion":"22.16.0","dependencies":{"nanoid":"^5.1.6","sqlite":"^5.1.1","js-yaml":"^4.1.1","sqlite3":"^5.1.7","commander":"^14.0.2","node-cron":"^4.2.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","eslint":"^9.39.2","ts-jest":"^29.4.6","prettier":"^3.7.4","typescript":"^5.9.3","@types/jest":"^30.0.0","@types/node":"^25.0.3","@types/js-yaml":"^4.0.9","@types/better-sqlite3":"^7.6.13","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","@typescript-eslint/parser":"^8.50.1","@typescript-eslint/eslint-plugin":"^8.50.1"},"_npmOperationalInternal":{"tmp":"tmp/fraud-guard_1.0.0_1767464382197_0.4388359121168759","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bolu1/fraud-guard","version":"1.0.1","description":"An on-premise fraud detection package for Node.js applications with incremental learning for it's AI model and velocity checks.","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"require":"./dist/index.js","import":"./dist/index.js","types":"./dist/index.d.ts"}},"bin":{"fraud-guard":"dist/cli/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","prepublishOnly":"npm run build","test":"jest","test:watch":"jest --watch","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","clean":"rm -rf dist"},"repository":{"type":"git","url":"git+https://github.com/bolu1/fraud-guard.git"},"keywords":["fraud","fraud-detection","payment-fraud","anomaly-detection","machine-learning","risk-scoring","chargeback-prevention","transaction-monitoring","velocity-checks","payment-security","ecommerce","fintech","typescript","self-hosted","ai","tensorflow","cnn","fraud-prevention","risk-assessment","behavioral-analysis"],"author":{"name":"Bolu boluadetifa@gmail.com"},"license":"MIT","type":"commonjs","bugs":{"url":"https://github.com/bolu1/fraud-guard/issues"},"homepage":"https://github.com/bolu1/fraud-guard#readme","dependencies":{"commander":"^14.0.2","js-yaml":"^4.1.1","nanoid":"^5.1.6","node-cron":"^4.2.1","sqlite":"^5.1.1","sqlite3":"^5.1.7"},"devDependencies":{"@types/better-sqlite3":"^7.6.13","@types/jest":"^30.0.0","@types/js-yaml":"^4.0.9","@types/node":"^25.0.3","@typescript-eslint/eslint-plugin":"^8.50.1","@typescript-eslint/parser":"^8.50.1","eslint":"^9.39.2","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","jest":"^30.2.0","prettier":"^3.7.4","ts-jest":"^29.4.6","typescript":"^5.9.3"},"_id":"@bolu1/fraud-guard@1.0.1","gitHead":"8f1d03f54535e2166d75eea433a48ba5cafc7d9a","_nodeVersion":"22.16.0","_npmVersion":"11.4.1","dist":{"integrity":"sha512-0OpSz+d+kRtLGx6xS4iVsvJIcVuSQtEGXDC0AJX1BnqIQQxR/v/11ONjUGNMgUXaEezn1LythAMxNu/g7X1FgQ==","shasum":"4c6ddc90c23fbd039b66049e45e9210e028c31f3","tarball":"https://registry.npmjs.org/@bolu1/fraud-guard/-/fraud-guard-1.0.1.tgz","fileCount":149,"unpackedSize":400213,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCADWjS7KaAT0Y24HDm6a33frTP6Iq4JTJ24iarQ1P7rgIgCQinMWo0ntuYHwPlkke5qEUgxqY5f8FKQ+alGnlFWDE="}]},"_npmUser":{"name":"bolu1","email":"boluadetifa@gmail.com"},"directories":{},"maintainers":[{"name":"bolu1","email":"boluadetifa@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fraud-guard_1.0.1_1775982684842_0.05018117222049412"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-03T18:19:42.095Z","modified":"2026-04-12T08:31:25.091Z","1.0.0":"2026-01-03T18:19:42.339Z","1.0.1":"2026-04-12T08:31:24.978Z"},"bugs":{"url":"https://github.com/bolu1/fraud-guard/issues"},"author":{"name":"Bolu boluadetifa@gmail.com"},"license":"MIT","homepage":"https://github.com/bolu1/fraud-guard#readme","keywords":["fraud","fraud-detection","payment-fraud","anomaly-detection","machine-learning","risk-scoring","chargeback-prevention","transaction-monitoring","velocity-checks","payment-security","ecommerce","fintech","typescript","self-hosted","ai","tensorflow","cnn","fraud-prevention","risk-assessment","behavioral-analysis"],"repository":{"type":"git","url":"git+https://github.com/bolu1/fraud-guard.git"},"description":"An on-premise fraud detection package for Node.js applications with incremental learning for it's AI model and velocity checks.","maintainers":[{"name":"bolu1","email":"boluadetifa@gmail.com"}],"readme":"\n# fraud-guard\n\nAn on-premise fraud detection package for Node.js applications with incremental learning for the AI model and velocity checks.\n<!-- \n[![npm version](https://badge.fury.io/js/fraud-guard.svg)](https://www.npmjs.com/package/fraud-guard)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -->\n\n**Key Features:**\n- 🤖 Real-time fraud detection using CNN model\n- 📈 Incremental learning - model improves with feedback\n- ⚡  Velocity checks for behavioral patterns\n- 💾 Completely on-premise\n- 🔄 Automatic model retraining *(beta)*\n- 📊 Model versioning and rollback\n- 👨🏾‍💻 CLI tool utility tools\n- 🚀 Zero external dependencies for inference\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Basic Usage](#basic-usage)\n- [Configuration](#configuration)\n  - [Configuration File Structure](#configuration-file-structure)\n  - [Configuration Options](#configuration-options)\n  - [Configuration Examples](#configuration-examples)\n- [Core Concepts](#core-concepts)\n- [Features](#features)\n  - [Velocity Checks](#velocity-checks)\n  - [Model Retraining](#model-retraining)\n  - [Model Management](#model-management)\n- [CLI Commands](#cli-commands)\n- [API Reference](#api-reference)\n- [Production Deployment](#production-deployment)\n- [Examples](#examples)\n- [Troubleshooting](#troubleshooting)\n- [FAQ](#faq)\n- [License](#license)\n\n---\n\n## Installation\n\n```bash\nnpm install @bolu1/fraud-guard\n```\n\nTypeScript types are included by default.\n\n---\n\n## Quick Start\n\n**1. Create a configuration file:**\n\nCreate `fraud-guard.config.yml` in your project root:\n\n```yaml\nproject:\n  name: \"my-app\"\n\nthresholds:\n  review: 0.4  # Flag for review if score > 40%\n  reject: 0.7  # Auto-reject if score > 70%\n```\n\n**2. Use in your application:**\n\n```typescript\nimport { FraudGuard } from '@bolu1/fraud-guard';\n\nconst guard = new FraudGuard();\n\nconst result = await guard.check({\n  amount: 1500.00,\n  category: 'shopping_net',\n  timestamp: new Date()\n});\n\nconsole.log(`Risk: ${result.risk}`);        // LOW, MEDIUM, HIGH, CRITICAL\nconsole.log(`Action: ${result.action}`);    // ACCEPT, REVIEW, REJECT\nconsole.log(`Score: ${result.score}%`);     // Fraud probability\n\nguard.close();\n```\n\n> **Note on transaction amounts:** The underlying model was trained on USD amounts, so `amount` must be in US dollars. If your application processes transactions in a different currency, you can either convert the amount to USD before calling `check()`, or set `dollar_conversion_rate` in your config file to have the package handle the conversion automatically (see [Configuration Options](#configuration-options)).\n\n---\n\n## Basic Usage\n\n### 1. Initialize Fraud Guard\n\n```typescript\nimport { FraudGuard } from '@bolu1/fraud-guard';\n\nconst guard = new FraudGuard();\n```\n\n### 2. Check Transactions\n\n```typescript\nconst transaction = {\n  amount: 250.50,\n  category: 'food_dining',\n  timestamp: new Date()\n};\n\nconst result = await guard.check(transaction);\n\n// Result contains:\n// - checkId: Unique identifier for this check\n// - score: Fraud probability (0-1, shown as percentage)\n// - risk: LOW | MEDIUM | HIGH | CRITICAL\n// - action: ACCEPT | REVIEW | REJECT\n// - velocityScore: (if velocity checks enabled)\n// - velocityChecks: Details of velocity violations\n```\n\n### 3. Handle Results\n\n```typescript\nswitch (result.action) {\n  case 'ACCEPT':\n    // Process transaction normally\n    await processPayment(transaction);\n    break;\n    \n  case 'REVIEW':\n    // Flag for manual review\n    await queueForReview(transaction, result);\n    break;\n    \n  case 'REJECT':\n    // Block transaction\n    throw new Error('Transaction rejected due to fraud risk');\n}\n```\n\n### 4. Provide Feedback (Optional but Recommended)\n\nAfter investigation, provide feedback for velocity checks to improve the model:\n\n```typescript\nimport { FraudGuard } from '@bolu1/fraud-guard';\n\nconst guard = new FraudGuard();\n\nconst result = await guard.check({\n  id: 'test_tx',           // Required when storage is enabled — use your own transaction ID so feedback is easy to correlate\n  customerId: 'user_123',  // Required when storage is enabled\n  amount: 1500.00,\n  category: 'shopping_net',\n  timestamp: new Date()\n});\n\n// Transaction was legitimate\nawait guard.feedback(transactionId, false); //same id passed when the transaction was checked\n\n// Transaction was fraud\nawait guard.feedback(transactionId, true);\n\n// Transaction with status(optional for failed transaction check)\nawait guard.feedback(transactionId, true, \"failed\");\n```\n\n### 5. Close When Done\n\n```typescript\n// Clean shutdown\nguard.close();\n```\n\n---\n\n## Configuration\n\n### Configuration File Structure\nYou can create an optional configuration file to access the additional functionalities of the package, without the configuration file, the AI model just makes a prediction using the baseline model\n\nCreate `fraud-guard.config.yml` in your project root:\n\n```yaml\n# Project identification (REQUIRED)\nproject:\n  name: \"my-ecommerce-store\"  # Unique name for this project\n\n# Fraud detection thresholds\nthresholds:\n  review: 0.4   # Score above 40% triggers review (default: 0.4)\n  reject: 0.7   # Score above 70% triggers rejection (default: 0.7)\n\ndollar_conversion_rate: 1500  # e.g. 1 USD = 1,500 NGN\n\n# Data storage for feedback and retraining\nstorage:\n  enabled: false                    # Enable storage (default: false)\n  path: null                        # Auto-generated if not specified\n  retention:\n    predictions_days: 90            # Keep predictions for 90 days (default: 90)\n\n# Custom model path (optional)\nmodel:\n  path: null                        # Use baseline model if not specified\n\n# Velocity checks - detect suspicious behavioral patterns\nvelocity:\n  enabled: false                    # Enable velocity checks (default: false)\n  scoring:\n    model_weight: 0.6               # Weight for ML model score (default: 0.6)\n    velocity_weight: 0.4            # Weight for velocity score (default: 0.4)\n  \n  # Transaction frequency rules\n  frequency:\n    enabled: true\n    time_windows:\n      - period_minutes: 10          # 5 transactions in 10 minutes\n        max_transactions: 5\n        score_adjustment: 0.2       # Adds 20% to fraud score\n      - period_minutes: 60          # 10 transactions in 1 hour\n        max_transactions: 10\n        score_adjustment: 0.3\n      - period_minutes: 1440        # 50 transactions in 24 hours\n        max_transactions: 50\n        score_adjustment: 0.4\n  \n  # Spending amount rules\n  amount:\n    enabled: true\n    time_windows:\n      - period_minutes: 60          # $5000 in 1 hour\n        max_amount: 5000\n        score_adjustment: 0.2\n      - period_minutes: 1440        # $10000 in 24 hours\n        max_amount: 10000\n        score_adjustment: 0.3\n    spike_detection:\n      enabled: true\n      lookback_days: 30             # Compare to last 30 days\n      multiplier: 5                 # 5x normal spending\n      score_adjustment: 0.4\n  \n  # Failed transaction monitoring\n  failed_transactions:\n    enabled: true\n    time_windows:\n      - period_minutes: 10          # 3 failures in 10 minutes\n        max_failed: 3\n        score_adjustment: 0.3\n      - period_minutes: 60          # 5 failures in 1 hour\n        max_failed: 5\n        score_adjustment: 0.4\n\n# Automatic model retraining\nretraining:\n  enabled: false                    # Enable retraining (default: false)\n  python_path: \"python3\"            # Python executable (default: python3)\n  python_venv: \"bin/python\"         # Virtual env relative path (default: bin/python)\n  min_samples: 100                  # Minimum feedback needed (default: 100)\n  schedule: \"0 2 * * *\"             # Cron schedule - 2 AM daily (default: 0 2 * * *)\n  retained_versions: 5              # Keep last 5 models (default: 5)\n\n# Logging configuration\nlogging:\n  level: \"INFO\"                     # DEBUG, INFO, WARN, ERROR (default: INFO)\n  console: true                     # Log to console (default: true)\n```\n\n### Configuration Options\n\n#### **Project Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `project.name` | string | Yes | - | Unique identifier for this project |\n\n#### **Threshold Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `thresholds.review` | number | No | 0.4 | Fraud score threshold for manual review (0-1) |\n| `thresholds.reject` | number | No | 0.7 | Fraud score threshold for automatic rejection (0-1) |\n\n#### **Storage Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `storage.enabled` | boolean | No | false | Enable data storage for feedback and retraining |\n| `storage.path` | string | No | auto | Path to SQLite database file |\n| `storage.retention.predictions_days` | number | No | 90 | Days to retain prediction history |\n\n#### **Currency Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `dollar_conversion_rate` | number | No | - | Number of your local currency units per 1 USD. When set, amounts are automatically divided by this rate before inference. If not set, amounts are assumed to already be in USD. |\n\n#### **Model Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `model.path` | string | No | baseline | Custom model directory path |\n\n#### **Velocity Check Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `velocity.enabled` | boolean | No | false | Enable behavioral pattern detection |\n| `velocity.scoring.model_weight` | number | No | 0.6 | Weight for ML model score in final calculation |\n| `velocity.scoring.velocity_weight` | number | No | 0.4 | Weight for velocity score in final calculation |\n| `velocity.frequency` | object | No | See config | Transaction frequency rules |\n| `velocity.amount` | object | No | See config | Spending amount rules |\n| `velocity.failed_transactions` | object | No | See config | Failed transaction rules |\n\n#### **Retraining Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `retraining.enabled` | boolean | No | false | Enable automatic model retraining |\n| `retraining.python_path` | string | No | \"python3\" | Path to Python executable |\n| `retraining.python_venv` | string | No | \"bin/python\" | Virtual environment path |\n| `retraining.min_samples` | number | No | 100 | Minimum feedback samples required for retraining |\n| `retraining.schedule` | string | No | \"0 2 * * *\" | Cron schedule for automatic retraining |\n| `retraining.retained_versions` | number | No | 5 | Number of model versions to keep |\n\n#### **Logging Settings**\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `logging.level` | string | No | \"INFO\" | Log level: DEBUG, INFO, WARN, ERROR |\n| `logging.console` | boolean | No | true | Enable console logging |\n\n### Configuration Examples\n\n#### **Minimal Configuration (Detection Only)**\n\n```yaml\nproject:\n  name: \"my-app\"\n\nthresholds:\n  review: 0.4\n  reject: 0.7\n```\n\n#### **With Storage (For feedback stored on-premise)**\n\n```yaml\nproject:\n  name: \"my-app\"\n\nthresholds:\n  review: 0.4\n  reject: 0.7\n\nstorage:\n  enabled: true\n  retention:\n    predictions_days: 90\n```\n\n#### **With Currency Conversion**\n\n```yaml\nproject:\n  name: \"my-app\"\n\nthresholds:\n  review: 0.4\n  reject: 0.7\n\ndollar_conversion_rate: 1500  # e.g. 1 USD = 1,500 NGN\n```\n\n#### **With Velocity Checks**\n\n```yaml\nproject:\n  name: \"my-app\"\n\nthresholds:\n  review: 0.4\n  reject: 0.7\n\nstorage:\n  enabled: true\n\nvelocity:\n  enabled: true\n  scoring:\n    model_weight: 0.6\n    velocity_weight: 0.4\n\n  # Transaction frequency rules\n  frequency:\n    enabled: true\n    time_windows:\n      - period_minutes: 10          # 5 transactions in 10 minutes\n        max_transactions: 5\n        score_adjustment: 0.2       # Adds 20% to fraud score\n      - period_minutes: 60          # 10 transactions in 1 hour\n        max_transactions: 10\n        score_adjustment: 0.3\n      - period_minutes: 1440        # 50 transactions in 24 hours\n        max_transactions: 50\n        score_adjustment: 0.4\n\n  # Spending amount rules\n  amount:\n    enabled: true\n    time_windows:\n      - period_minutes: 60          # $5000 in 1 hour\n        max_amount: 5000\n        score_adjustment: 0.2\n      - period_minutes: 1440        # $10000 in 24 hours\n        max_amount: 10000\n        score_adjustment: 0.3\n    spike_detection:\n      enabled: true\n      lookback_days: 30             # Compare to last 30 days\n      multiplier: 5                 # 5x normal spending triggers flag\n      score_adjustment: 0.4\n\n  # Failed transaction monitoring\n  failed_transactions:\n    enabled: true\n    time_windows:\n      - period_minutes: 10          # 3 failures in 10 minutes\n        max_failed: 3\n        score_adjustment: 0.3\n      - period_minutes: 60          # 5 failures in 1 hour\n        max_failed: 5\n        score_adjustment: 0.4\n```\n\n---\n\n## Core Concepts\n\n### How Fraud Detection Works\n\n1. **ML Model Scoring**: A CNN model analyzes transaction features (amount, time, category, etc.) and outputs a fraud probability (0-1)\n2. **Velocity Checks** (optional): Behavioral pattern analysis adds context-based risk scoring\n3. **Combined Scoring**: If velocity is enabled, scores are weighted and combined\n4. **Threshold Evaluation**: Final score is compared against review/reject thresholds\n5. **Action Recommendation**: Returns ACCEPT, REVIEW, or REJECT\n\n### Thresholds\n\n- **Review threshold** (default 0.4): Scores above this trigger manual review\n- **Reject threshold** (default 0.7): Scores above this trigger automatic rejection\n- **Risk levels**:\n  - LOW: score < review threshold\n  - MEDIUM: review ≤ score < reject\n  - HIGH: score ≥ reject threshold\n  - CRITICAL: score ≥ 0.9\n\n### Feedback Loop\n\nProviding feedback after manual review helps the model learn:\n\n```typescript\n// After confirming transaction was fraud\nawait guard.feedback(checkId, true);\n\n// After confirming transaction was legitimate\nawait guard.feedback(checkId, false);\n```\n\nThe model uses this feedback during automatic retraining to improve accuracy.\n\n### Velocity Checks\n\nVelocity checks detect suspicious behavioral patterns:\n\n- **Frequency**: Too many transactions in short time\n- **Amount**: Unusual spending patterns or spikes\n- **Failed attempts**: Multiple failed transactions\n\nThese checks complement the ML model by catching behavioral red flags.\n\n### Model Retraining *(beta)*\n\nWhen enabled, the model automatically retrains on new feedback data:\n\n1. Runs on schedule (default: 2 AM daily)\n2. Requires minimum feedback samples (default: 100)\n3. Creates new model version only if accuracy improves\n4. Automatically loads improved model (no restart needed)\n5. Keeps last N versions for rollback (default: 5)\n\n---\n\n## Features\n\n### Velocity Checks\n\n**What They Detect:**\n- Rapid transaction bursts (credential testing)\n- Unusual spending spikes (compromised accounts)\n- Multiple failed attempts (brute force)\n\n**Configuration:**\n\n```yaml\nvelocity:\n  enabled: true\n  frequency:\n    time_windows:\n      - period_minutes: 10\n        max_transactions: 5\n        score_adjustment: 0.2\n```\n\n**Example Result:**\n\n```typescript\n{\n  score: 45.2,\n  velocityScore: 20.0,\n  velocityChecks: [\n    {\n      type: 'frequency',\n      period: 10,\n      count: 7,\n      limit: 5,\n      adjustment: 0.2\n    }\n  ]\n}\n```\n\n### Model Retraining *(beta)*\n\n**Setup:**\n\n```bash\n# 1. Install Python dependencies\nnpx fraud-guard setup-retraining\n\n# 2. Enable in config\n```\n\n```yaml\nretraining:\n  enabled: true\n  min_samples: 100\n  schedule: \"0 2 * * *\"  # Daily at 2 AM\n```\n\n**How It Works:**\n\n1. Collects feedback from `provideFeedback()` calls\n2. Waits for minimum samples (default: 100)\n3. Runs scheduled retraining (default: 2 AM daily)\n4. Compares new model accuracy to current\n5. Deploys new model if better (automatic, no restart)\n6. Keeps last 5 versions for rollback\n\n**Manual Trigger:**\n\n```bash\nnpx fraud-guard retrain\n```\n\n**Monitoring:**\n\n```bash\n# View retraining statistics\nnpx fraud-guard prediction-stats\n```\n\n### Model Management\n\n**List Available Models:**\n\n```bash\nnpx fraud-guard list-models\n```\n\nOutput:\n```\n● 20260103_163557\n  Created:  Jan 3, 2026, 4:35:57 PM\n  Accuracy: 98.50%\n  Samples:  120\n\n  20260103_160412\n  Created:  Jan 3, 2026, 4:04:12 PM\n  Accuracy: 97.80%\n  Samples:  100\n\n  v1.0.0 [BASELINE]\n  Created:  Jan 1, 2026, 12:00:00 AM\n  Accuracy: 95.00%\n  Samples:  1000\n```\n\n**Switch Model Version:**\n\n```bash\nnpx fraud-guard switch-model 20260103_160412\n```\n\n**Programmatic Access:**\n\n```typescript\n// List all models\nconst models = await guard.listModels();\n\n// Switch to specific version\nawait guard.switchModel('20260103_160412');\n```\n\n---\n\n## CLI Commands\n\n```bash\nnpx fraud-guard --help                    # Show help\nnpx fraud-guard setup-retraining   # Setup Python environment\nnpx fraud-guard model-info         # Current model information\nnpx fraud-guard prediction-stats   # Feedback statistics\nnpx fraud-guard retrain            # Manual retraining\nnpx fraud-guard list-models        # List all model versions\nnpx fraud-guard switch-model <ver> # Switch active model\n```\n\n### setup-retraining\n\nSetup Python virtual environment and install dependencies for model retraining.\n\n```bash\nnpx fraud-guard setup-retraining\n```\n\n### model-info\n\nDisplay current model information and configuration.\n\n```bash\nnpx fraud-guard model-info\n```\n\nOutput:\n```\nCurrent Model: v1.0.0 (baseline)\nLocation: ~/.fraud-guard/baseline\n\nConfiguration:\n  Project: my-app\n  Storage: Enabled\n  Velocity: Disabled\n  Retraining: Enabled\n```\n\n### prediction-stats\n\nView feedback statistics and retraining readiness.\n\n```bash\nnpx fraud-guard prediction-stats\n```\n\nOutput:\n```\nTotal Predictions: 1,250\nPredictions with Feedback: 85\nFeedback Rate: 6.8%\n\nRetraining Status:\n  Minimum Required: 100 samples\n  Currently Have: 85 samples\n  Ready to Retrain: No (need 15 more)\n```\n\n### retrain\n\nManually trigger model retraining.\n\n```bash\nnpx fraud-guard retrain\n```\n\n### list-models\n\nList all available model versions.\n\n```bash\nnpx fraud-guard list-models\n```\n\n### switch-model\n\nSwitch to a different model version.\n\n```bash\nnpx fraud-guard switch-model 20260103_163557\n```\n\n---\n\n## API Reference\n\n### FraudGuard Class\n\n```typescript\nimport { FraudGuard } from '@bolu1/fraud-guard';\n```\n\n#### Constructor\n\n```typescript\nconst guard = new FraudGuard();\n```\n\nLoads configuration from `fraud-guard.config.yml`.\n\n#### Methods\n\n**`check(transaction: TransactionData): Promise<FraudCheckResult>`**\n\nCheck a transaction for fraud.\n\n```typescript\nconst result = await guard.check({\n  amount: 150.00,\n  category: 'shopping_net',\n  timestamp: new Date(),\n  customerId: 'user_123',\n  ipAddress: '192.168.1.1',\n  deviceId: 'device_abc'\n});\n```\n\n**`provideFeedback(checkId: string, isFraud: boolean): Promise<void>`**\n\nProvide feedback on a previous fraud check.\n\n```typescript\nawait guard.feedback(result.checkId, true);\n```\n\n**`retrain(): Promise<RetrainingResult>`**\n\nManually trigger model retraining.\n\n```typescript\nconst result = await guard.retrain();\nconsole.log(`New model accuracy: ${result.metrics.accuracy}`);\n```\n\n**`listModels(): Promise<ModelVersion[]>`**\n\nList all available model versions.\n\n```typescript\nconst models = await guard.listModels();\nmodels.forEach(m => console.log(`${m.version}: ${m.accuracy}`));\n```\n\n**`switchModel(version: string): Promise<void>`**\n\nSwitch to a different model version.\n\n```typescript\nawait guard.switchModel('20260103_160412');\n```\n\n**`close(): void`**\n\nClean shutdown - stops scheduled jobs and closes connections.\n\n```typescript\nguard.close();\n```\n\n### Types\n\n**TransactionData**\n\n```typescript\ninterface TransactionData {\n  amount: number;\n  category: string;\n  timestamp: Date;\n  customerId?: string;\n  ipAddress?: string;\n  deviceId?: string;\n  id?: string;\n}\n```\n\n**FraudCheckResult**\n\n```typescript\ninterface FraudCheckResult {\n  checkId: string;\n  score: number;              // 0-100\n  risk: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';\n  action: 'ACCEPT' | 'REVIEW' | 'REJECT';\n  velocityScore?: number;\n  velocityChecks?: VelocityCheck[];\n}\n```\n\n**RetrainingResult**\n\n```typescript\ninterface RetrainingResult {\n  success: boolean;\n  version?: string;\n  metrics?: {\n    accuracy: number;\n    precision: number;\n    recall: number;\n    f1: number;\n    auc: number;\n  };\n  improvement?: number;\n  error?: string;\n}\n```\n\n---\n\n## Production Deployment\n\n### Best Practices\n\n**1. Enable Storage**\n```yaml\nstorage:\n  enabled: true\n```\n\n**2. Configure Appropriate Thresholds**\n\nAdjust based on your risk tolerance:\n- Conservative: `review: 0.3, reject: 0.6`\n- Balanced: `review: 0.4, reject: 0.7` (default)\n- Aggressive: `review: 0.5, reject: 0.8`\n\n**3. Enable Velocity Checks**\n\nFor payment processing, velocity checks significantly improve detection.\n\n**4. Provide Feedback Consistently**\n\nThe model only improves if you provide feedback on reviewed cases.\n\n**5. Monitor Retraining**\n\nCheck logs to ensure retraining completes successfully:\n```bash\nnpx fraud-guard prediction-stats\n```\n\n**6. Database Cleanup**\n\nAutomatic cleanup runs daily. Adjust retention as needed:\n```yaml\nstorage:\n  retention:\n    predictions_days: 90\n```\n\n### On-Premise Storage\n\nEverything is stored locally on your machine under `~/.fraud-guard/`. No data is sent to any external service.\n\n```\n~/.fraud-guard/\n├── baseline/                         # Shared baseline model (all projects)\n└── projects/\n    └── <your-project-name>/\n        ├── models/                   # Trained model versions\n        └── data/\n            └── fraud-data.db         # SQLite database (predictions & feedback)\n```\n\nThe database path and model path can be overridden in your config:\n\n```yaml\nstorage:\n  path: \"/your/custom/path/fraud-data.db\"\n\nmodel:\n  path: \"/your/custom/path/models\"\n```\n\n### Security\n\n- **Data Retention**: Configure appropriate retention for compliance (GDPR, etc.)\n- **PII Handling**: customerID, IP, deviceID are optional - exclude if not needed\n- **Model Security**: Model files stored on-premise in `~/.fraud-guard/` with user permissions\n- **Database**: SQLite database uses filesystem permissions\n\n---\n\n## Examples\n\n### E-commerce Checkout\n\n```typescript\nimport { FraudGuard } from '@bolu1/fraud-guard';\nimport express from 'express';\n\nconst app = express();\nconst guard = new FraudGuard();\n\napp.post('/checkout', async (req, res) => {\n  const { userId, amount, cartItems, ip, deviceId } = req.body;\n  \n  // Check for fraud\n  const result = await guard.check({\n    amount,\n    category: 'shopping_net',\n    timestamp: new Date(),\n    customerId: userId,\n    ipAddress: ip,\n    deviceId\n  });\n  \n  switch (result.action) {\n    case 'ACCEPT':\n      await processOrder(req.body);\n      res.json({ success: true });\n      break;\n      \n    case 'REVIEW':\n      await flagForReview(req.body, result);\n      res.json({ success: true, review: true });\n      break;\n      \n    case 'REJECT':\n      res.status(403).json({ error: 'Payment declined' });\n      break;\n  }\n});\n\n// After manual review\napp.post('/review/:checkId', async (req, res) => {\n  const { isFraud } = req.body;\n  await guard.feedback(req.params.checkId, isFraud);\n  res.json({ success: true });\n});\n```\n\n### Payment Gateway Integration\n\n```typescript\nasync function processPayment(payment: Payment) {\n  const fraudCheck = await guard.check({\n    amount: payment.amount,\n    category: payment.category,\n    timestamp: new Date(),\n    customerId: payment.customerId,\n    ipAddress: payment.metadata.ip,\n    deviceId: payment.metadata.device\n  });\n  \n  // Add fraud score to payment metadata\n  payment.metadata.fraudScore = fraudCheck.score;\n  payment.metadata.fraudCheckId = fraudCheck.checkId;\n  \n  if (fraudCheck.action === 'REJECT') {\n    throw new PaymentError('Transaction blocked - fraud risk');\n  }\n  \n  if (fraudCheck.action === 'REVIEW') {\n    payment.status = 'PENDING_REVIEW';\n    await sendToReviewQueue(payment);\n  } else {\n    payment.status = 'APPROVED';\n    await executePayment(payment);\n  }\n  \n  return payment;\n}\n```\n\n### Subscription Fraud Detection\n\n```typescript\nasync function createSubscription(user: User, plan: Plan) {\n  // Check signup for fraud\n  const result = await guard.check({\n    amount: plan.price,\n    category: 'misc_net',\n    timestamp: new Date(),\n    customerId: user.id,\n    ipAddress: user.signupIp,\n    deviceId: user.deviceFingerprint\n  });\n  \n  if (result.risk === 'HIGH' || result.risk === 'CRITICAL') {\n    // Require additional verification\n    await sendVerificationEmail(user);\n    await requirePhoneVerification(user);\n  }\n  \n  // Track the check ID for later feedback\n  const subscription = await createSub(user, plan);\n  subscription.fraudCheckId = result.checkId;\n  \n  return subscription;\n}\n\n// After user proves legitimacy (or commits fraud)\nasync function updateFraudStatus(subscription: Subscription) {\n  if (subscription.fraudCheckId) {\n    await guard.feedback(\n      subscription.fraudCheckId,\n      subscription.isFraud\n    );\n  }\n}\n```\n\n---\n\n## Troubleshooting\n\n### Python Environment Issues\n\n**Problem**: `npx fraud-guard setup-retraining` fails\n\n**Solution**:\n- Ensure Python 3.8+ is installed: `python3 --version`\n- On Ubuntu, install venv: `sudo apt-get install python3-venv`\n- Check Python path in config matches your system\n\n### Model Not Loading\n\n**Problem**: \"Model file not found\" error\n\n**Solution**:\n- Verify baseline model exists: `ls ~/.fraud-guard/baseline/`\n- Check model.path in config if using custom model\n- Ensure model directory contains all required files (model.json, etc.)\n\n### Storage Connection Errors\n\n**Problem**: \"Storage not initialized\" error\n\n**Solution**:\n- Enable storage in config: `storage.enabled: true`\n- Verify database path is writable\n- Check disk space\n\n### Retraining Failures\n\n**Problem**: Retraining completes but model not improving\n\n**Solution**:\n- Ensure sufficient feedback data (100+ samples)\n- Check feedback quality - balance of fraud/legitimate\n- Review Python logs for training errors\n\n### Performance Issues\n\n**Problem**: Slow fraud checks\n\n**Solution**:\n- Disable velocity checks if not needed\n- Reduce database retention period\n- Use appropriate hardware (model runs on CPU)\n\n---\n\n## FAQ\n\n\n**Q: What data is stored?**\n\nA: Only prediction results and feedback. Raw transaction data is not stored. You control retention period via config.\n\n**Q: Can I use my own model?**\n\nA: Yes, specify `model.path` in config. Model must be TensorFlow.js format with matching feature structure.\n\n**Q: How much does retraining cost (compute)?**\n\nA: Retraining typically takes 30-60 seconds on a standard CPU. No GPU required.\n\n**Q: Does it work offline?**\n\nA: Yes, fraud detection works completely offline. Only retraining requires Python packages (one-time install).\n\n**Q: How is this different from rule-based systems?**\n\nA: ML models detect patterns humans miss. Velocity rules complement ML for known attack patterns.\n\n**Q: Can I customize velocity rules?**\n\nA: Yes, all velocity thresholds and time windows are configurable in `fraud-guard.config.yml`.\n\n---\n\n## License\n\nMIT License - see LICENSE file for details\n\n---\n\n## 📞 Support\n\nFor issues and questions, please visit our [GitHub repository](https://github.com/Bolu1/fraud-guard).","readmeFilename":"README.md"}