CouponGuard — Ultra-Pro Coupon Protection System

Stop losing revenue to leaked discount codes.
CouponGuard is an enterprise-grade Node.js package that wraps every coupon you issue with multi-layer protection: device + IP locking, intelligent leak detection, automated deactivation, real-time alerts (Email / Slack / Webhook), and deep analytics.

Table of Contents

• Why CouponGuard?
• Architecture Overview
• Quick Start
• Configuration
• Core API
• Leak Detection Engine
• Notification Channels
• REST API Endpoints
• Analytics
• Pricing Plans
• Security
• Contributing
• License

Why CouponGuard?

| Problem | Without CouponGuard | With CouponGuard | |---|---|---| | Coupon shared on social media | Thousands of unintended uses | Blocked after first device/IP change | | No leak attribution | Unknown origin | Full audit trail per device & IP | | Manual response time | Hours / days | Automated deactivation in <1 s | | Revenue impact | Millions lost per campaign | Near-zero unintended redemptions |

Architecture Overview

coupon-guard/
├── src/
│   ├── config/          # DB, Redis, constants
│   ├── core/            # CouponGuard · CouponValidator · LeakDetector · RateLimiter
│   ├── models/          # Mongoose schemas
│   ├── services/        # CouponService · NotificationService · AnalyticsService · SecurityService
│   ├── middleware/       # auth · validator · errorHandler
│   ├── routes/          # Express routers
│   ├── utils/           # logger · encryption · validators · helpers
│   └── templates/       # Email & notification templates
├── tests/               # unit / integration / e2e
├── docs/                # Full documentation
├── examples/            # Ready-to-run examples
└── scripts/             # setup · migrate · seed

Quick Start

# 1. Install
npm install coupon-guard

# 2. Copy and fill environment variables
cp .env.example .env

# 3. Run setup (creates indexes, validates env)
npm run setup

# 4. Apply DB migrations
npm run migrate

# 5. (Optional) Seed demo data
npm run seed

# 6. Start
npm start

Minimal Usage

import CouponGuard from 'coupon-guard';

const guard = new CouponGuard({
  maxUsesDefault: 100,
  lockType: 'device+ip',
  leakAction: 'alert',
});

// Create
const coupon = await guard.create('SAVE50', {
  discount: 50,
  discountType: 'fixed',
  maxUses: 100,
  expiryDate: new Date('2025-12-31'),
});

// Validate
const result = await guard.validate('SAVE50', {
  userId: 'usr_123',
  deviceId: 'dev_abc',
  ipAddress: '1.2.3.4',
});

if (result.valid) {
  console.log(`Apply discount: ${result.discount}`);
} else {
  console.log(`Rejected: ${result.reason}`);
}

// Stats
const stats = await guard.getStatistics('SAVE50');
console.log(stats);

Configuration

| Option | Type | Default | Description | |---|---|---|---| | maxUsesDefault | number | 100 | Global max-uses fallback | | lockType | string | device+ip | none | device | ip | device+ip | | leakAction | string | alert | alert | block | auto-deactivate | | leakThreshold | number | 5 | Unique devices/IPs before leak is raised | | timeWindow | number | 3600000 | Detection window in ms (default 1 h) | | rateLimitWindow | number | 60000 | Rate-limit window in ms | | rateLimitMax | number | 10 | Max requests per window per IP |

All settings can be overridden via environment variables — see .env.example.

Core API

guard.create(code, options)

guard.validate(code, context)

guard.deactivate(code)

guard.reactivate(code)

guard.getStatistics(code)

guard.bulkCreate(coupons[])

guard.bulkDeactivate(codes[])

guard.listLeakAlerts(filters)

Full JSDoc in docs/API.md.

Leak Detection Engine

Three detection strategies run in parallel on every validation call:

1. Device/IP Change — first-use lock fingerprint comparison
2. Multiple Devices/IPs — threshold breach within time window
3. Abnormal Usage Rate — requests/min spike detection

Severity scale: low → medium → high → critical

Notification Channels

| Channel | Trigger | Config Key | |---|---|---| | Email (SMTP) | Any leak alert | EMAIL_* | | Slack Webhook | high / critical | SLACK_WEBHOOK_URL | | Generic Webhook | All events | WEBHOOK_URL | | In-app alert | Dashboard | automatic |

REST API Endpoints

| Method | Path | Description | |---|---|---| | POST | /api/v1/coupons | Create coupon | | GET | /api/v1/coupons/:code | Get coupon details | | PUT | /api/v1/coupons/:code | Update coupon | | DELETE | /api/v1/coupons/:code | Deactivate coupon | | POST | /api/v1/coupons/:code/validate | Validate & redeem | | GET | /api/v1/coupons/:code/stats | Statistics | | GET | /api/v1/alerts | List leak alerts | | GET | /api/v1/analytics/overview | Dashboard overview | | GET | /api/v1/health | Health check |

Full Swagger UI at /api-docs when server is running.

Pricing Plans

| Plan | Price | Coupons | Detection | Auto-Actions | Support | |---|---|---|---|---|---| | Free | $0 / mo | 50 | Basic | ❌ | Email | | Pro | $17 / mo | Unlimited | Advanced | ✅ | Priority | | Enterprise | Custom | Unlimited | Custom | ✅ | 24/7 + SLA |

Security

• AES-256 encryption for cached coupon data
• bcrypt hashing for device fingerprints
• HMAC-SHA256 signed webhook payloads
• Helmet + CORS + Rate Limiting on all routes
• JWT authentication for the management API

See docs/SECURITY.md for full threat model.

License

MIT © CouponGuard Team