chargeback-guard 2.0.0

package/docs/getting-started.md

@@ -0,0 +1,155 @@
+# Getting Started with chargeback-guard
+
+chargeback-guard is an ultra-pro chargeback protection system for e-commerce merchants. It automatically collects transaction evidence, detects payment disputes, scores fraud risk with AI, and submits structured replies to banks via Stripe / PayPal / Square / Braintree webhooks.
+
+---
+
+## Installation
+
+```bash
+npm install chargeback-guard
+```
+
+### Peer Dependencies
+
+| Dependency | Purpose |
+|---|---|
+| `stripe` | Stripe webhook handling & dispute submission |
+| `paypal-rest-sdk` | PayPal dispute API (optional) |
+| `dotenv` | Environment variable loading |
+
+---
+
+## Quick Start
+
+### 1. Set Environment Variables
+
+Create a `.env` file:
+
+```dotenv
+CHARGEBACK_API_KEY=your-api-key-here
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+DATABASE_URL=sqlite://./data/chargeback-guard.db
+NODE_ENV=production
+```
+
+### 2. Initialize the Guard
+
+```typescript
+import { createChargebackGuard } from 'chargeback-guard';
+
+const guard = await createChargebackGuard({
+  apiKey: process.env.STRIPE_SECRET_KEY!,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+  autoReply: true,
+  evidenceCollection: true,
+});
+
+console.log('ChargebackGuard is running ✓');
+```
+
+### 3. Register a Payment
+
+Call `registerPayment()` immediately after every successful charge. This pre-collects evidence so it is ready if a dispute arrives later.
+
+```typescript
+const result = await guard.registerPayment({
+  orderId:      'order_abc123',
+  customerId:   'cust_xyz',
+  amount:       9999,          // cents
+  currency:     'USD',
+  provider:     'stripe',
+  transactionId: 'ch_3Pabcdef...',
+  timestamp:    new Date(),
+  metadata: {
+    email:          'customer@example.com',
+    ipAddress:      '203.0.113.42',
+    deviceId:       'fp_abc123',
+    shippingAddress: '123 Main St, Austin TX 78701',
+  },
+});
+
+console.log('Risk level:', result.riskLevel);  // 'very_low' | 'low' | 'medium' | 'high' | 'critical'
+console.log('Trust score:', result.trustScore); // 0–100
+```
+
+### 4. Handle Disputes via Webhook
+
+```typescript
+import express from 'express';
+
+const app = express();
+
+// Raw body needed for Stripe signature verification
+app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
+  const sig = req.headers['stripe-signature'] as string;
+
+  // Verify + parse the Stripe event yourself, then call handleDispute()
+  const dispute = {
+    id:           event.data.object.id,
+    orderId:      event.data.object.metadata.orderId,
+    amount:       event.data.object.amount,
+    currency:     event.data.object.currency,
+    reason:       event.data.object.reason,
+    status:       event.data.object.status,
+    provider:     'stripe' as const,
+    dueBy:        new Date(event.data.object.evidence_details.due_by * 1000),
+    createdAt:    new Date(),
+  };
+
+  const outcome = await guard.handleDispute(dispute);
+  console.log('Action taken:', outcome.actionTaken);
+  // 'auto-reply_submitted' | 'manual_review_required' | 'accepted' | 'skipped'
+
+  res.json({ received: true });
+});
+
+app.listen(3000);
+```
+
+### 5. Graceful Shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+  await guard.shutdown();
+  process.exit(0);
+});
+```
+
+---
+
+## Core Concepts
+
+### Payment Registration
+Every successful transaction should be registered. chargeback-guard:
+- Collects device fingerprints, geolocation, and behavioral signals
+- Runs an AI fraud pre-check and assigns a trust score (0–100)
+- Stores all evidence in the configured database, indexed by `orderId`
+
+### Dispute Detection
+When a chargeback is filed, `handleDispute()`:
+1. Fetches all pre-collected evidence for the associated `orderId`
+2. Analyzes the dispute reason and selects a response strategy
+3. Optionally auto-submits a reply to the payment provider
+
+### Auto-Reply
+When `autoReply: true`, chargeback-guard submits evidence to the bank on your behalf within minutes of dispute detection — maximizing win rates by responding before the deadline.
+
+### Risk Levels
+
+| Level | Trust Score | Meaning |
+|---|---|---|
+| `very_low` | 80–100 | Fully trusted — registered customer, normal pattern |
+| `low` | 60–79 | Minor signals — investigate if disputed |
+| `medium` | 40–59 | Moderate risk — watch for chargebacks |
+| `high` | 20–39 | High fraud probability — consider hold |
+| `critical` | 0–19 | Very high risk — block or manual review |
+
+---
+
+## Next Steps
+
+- [API Reference](./api.md)
+- [Configuration](./configuration.md)
+- [Architecture](./architecture.md)

package/examples/advancedConfig.ts

@@ -0,0 +1,123 @@
+// ============================================================
+//  CHARGEBACK GUARD — Advanced Configuration Example
+// ============================================================
+
+import {
+  ChargebackGuard,
+  Environment,
+  NotificationEvent,
+  NotificationChannel,
+  SubscriptionPlan,
+} from '../src';
+
+async function advancedSetup(): Promise<void> {
+  // ── Full configuration ────────────────────────────────────
+  const guard = new ChargebackGuard({
+    environment: Environment.PRODUCTION,
+    autoReply: true,
+    evidenceCollection: true,
+
+    database: {
+      type: 'postgresql',
+      url: process.env.DATABASE_URL ?? 'postgresql://localhost/chargebackguard',
+      poolMin: 2,
+      poolMax: 20,
+    },
+
+    redis: {
+      url: process.env.REDIS_URL ?? 'redis://localhost:6379',
+      ttl: 7200,
+    },
+
+    security: {
+      jwtSecret: process.env.JWT_SECRET ?? 'change-me',
+      encryptionKey: process.env.ENCRYPTION_KEY ?? 'change-this-32-char-key-produc!!',
+      bcryptRounds: 14,
+      rateLimit: {
+        windowMs: 900000,
+        maxRequests: 200,
+      },
+    },
+
+    notifications: {
+      channels: [
+        NotificationChannel.EMAIL,
+        NotificationChannel.SMS,
+        NotificationChannel.WEBHOOK,
+        NotificationChannel.IN_APP,
+      ],
+      email: {
+        host: 'smtp.sendgrid.net',
+        port: 587,
+        secure: false,
+        user: 'apikey',
+        pass: process.env.SENDGRID_API_KEY ?? '',
+        fromName: 'Chargeback Guard',
+        fromAddress: 'alerts@chargebackguard.io',
+      },
+      sms: {
+        accountSid: process.env.TWILIO_SID ?? '',
+        authToken: process.env.TWILIO_TOKEN ?? '',
+        phoneNumber: process.env.TWILIO_PHONE ?? '',
+      },
+      webhooks: [
+        {
+          url: 'https://your-app.com/webhooks/chargebackguard',
+          secret: process.env.WEBHOOK_SECRET,
+          events: [
+            NotificationEvent.DISPUTE_DETECTED,
+            NotificationEvent.DISPUTE_WON,
+            NotificationEvent.DISPUTE_LOST,
+            NotificationEvent.FRAUD_DETECTED,
+          ],
+          retries: 3,
+        },
+      ],
+    },
+
+    ai: {
+      fraudThreshold: 0.70,
+      riskScoreHigh: 0.85,
+      riskScoreMedium: 0.50,
+    },
+
+    billing: {
+      plan: SubscriptionPlan.ENTERPRISE,
+      revenueSharePercentage: 0.8,
+      monthlyPrice: 499,
+    },
+  });
+
+  // ── Custom event handlers ─────────────────────────────────
+
+  guard.events.onAsync(NotificationEvent.DISPUTE_DETECTED, async ({ data }) => {
+    // Your custom logic: update CRM, send Slack notification, etc.
+    console.log(`[CUSTOM] Dispute received: ${data['disputeId']}`);
+  });
+
+  guard.events.onAsync(NotificationEvent.DISPUTE_WON, async ({ data }) => {
+    const amount = (Number(data['amount']) || 0) / 100;
+    console.log(`[CUSTOM] $${amount.toFixed(2)} recovered for dispute ${data['disputeId']}`);
+    // e.g., update accounting system, notify customer success team
+  });
+
+  guard.events.onAsync(NotificationEvent.FRAUD_DETECTED, async ({ data }) => {
+    console.log(`[CUSTOM] FRAUD on order ${data['orderId']} — probability: ${data['probability']}`);
+    // e.g., block the customer account, flag for review
+  });
+
+  // ── Initialize ────────────────────────────────────────────
+  await guard.initialize();
+
+  // ── Check health ──────────────────────────────────────────
+  const health = await guard.getHealth();
+  console.log('Health:', JSON.stringify(health.data, null, 2));
+
+  // ── Lifetime stats ────────────────────────────────────────
+  const stats = await guard.getProtectionStats();
+  console.log('\nStats:', JSON.stringify(stats, null, 2));
+
+  await guard.shutdown();
+}
+
+advancedSetup().catch(console.error);

package/examples/basicUsage.ts

@@ -0,0 +1,98 @@
+// ============================================================
+//  CHARGEBACK GUARD — Basic Usage Example
+// ============================================================
+
+import { createChargebackGuard, NotificationEvent, PaymentProvider } from '../src';
+
+async function main(): Promise<void> {
+  // ── 1. Initialize ─────────────────────────────────────────
+  console.log('🚀 Initializing ChargebackGuard...');
+
+  const guard = await createChargebackGuard({
+    autoReply: true,
+    evidenceCollection: true,
+  });
+
+  // ── 2. Listen for events ──────────────────────────────────
+  guard.events.on(NotificationEvent.PAYMENT_REGISTERED, ({ data }) => {
+    console.log(`✅ Payment protected: ${data['orderId']} | Trust: ${data['trustScore']}`);
+  });
+
+  guard.events.on(NotificationEvent.DISPUTE_DETECTED, ({ data }) => {
+    console.log(`⚠️  Dispute detected: ${data['disputeId']} — auto-reply in progress`);
+  });
+
+  guard.events.on(NotificationEvent.DISPUTE_REPLIED, ({ data }) => {
+    console.log(`📤 Reply submitted for: ${data['disputeId']}`);
+  });
+
+  guard.events.on(NotificationEvent.DISPUTE_WON, ({ data }) => {
+    console.log(`🏆 WON: ${data['disputeId']} | $${((Number(data['amount']) || 0) / 100).toFixed(2)} recovered`);
+  });
+
+  // ── 3. Register a payment ──────────────────────────────────
+  const registration = await guard.registerPayment({
+    orderId: 'ORD-2025-12345',
+    amount: 29999,          // cents = $299.99
+    currency: 'USD',
+    customerEmail: 'alice@example.com',
+    customerName: 'Alice Johnson',
+    customerIp: '203.0.113.42',
+    transactionId: 'ch_3OqExample123',
+    provider: PaymentProvider.STRIPE,
+    shippingAddress: {
+      line1: '123 Main Street',
+      city: 'Cairo',
+      postalCode: '11511',
+      country: 'EG',
+    },
+    sessionData: {
+      sessionId: 'sess_abc123',
+      duration: 340,
+      pageViews: [
+        { url: '/products/item-123', duration: 120, timestamp: new Date().toISOString() },
+        { url: '/cart', duration: 45,  timestamp: new Date().toISOString() },
+        { url: '/checkout', duration: 90, timestamp: new Date().toISOString() },
+      ],
+      timeOnCheckout: 90,
+    },
+    deviceFingerprint: {
+      screenResolution: '1920x1080',
+      timezone: 'UTC+2',
+      language: 'en-US',
+      platform: 'Win32',
+    },
+  });
+
+  console.log('\n📦 Registration Result:');
+  console.log(JSON.stringify(registration, null, 2));
+
+  // ── 4. Simulate a dispute ──────────────────────────────────
+  console.log('\n🚨 Simulating incoming dispute...');
+
+  const disputeResult = await guard.handleDispute({
+    id: 'dp_2OqTestDispute001',
+    orderId: 'ORD-2025-12345',
+    amount: 29999,
+    currency: 'usd',
+    reason: 'product_not_received' as never,
+    status: 'needs_response' as never,
+    provider: PaymentProvider.STRIPE,
+    evidenceDueBy: new Date(Date.now() + 7 * 86400000).toISOString(), // 7 days
+    createdAt: new Date().toISOString(),
+  });
+
+  console.log('\n📋 Dispute Handling Result:');
+  console.log(JSON.stringify(disputeResult, null, 2));
+
+  // ── 5. Get stats ───────────────────────────────────────────
+  const stats = await guard.getProtectionStats();
+  console.log('\n📊 Protection Stats:');
+  console.log(JSON.stringify(stats, null, 2));
+
+  // ── 6. Shutdown ────────────────────────────────────────────
+  await guard.shutdown();
+  console.log('\n✅ ChargebackGuard shut down gracefully');
+}
+
+main().catch(console.error);

package/examples/stripeIntegration.ts

@@ -0,0 +1,106 @@
+// ============================================================
+//  CHARGEBACK GUARD — Stripe Integration Example (Express App)
+// ============================================================
+
+import express from 'express';
+import { createChargebackGuard, PaymentProvider, DisputeStatus } from '../src';
+import { WebhookHandler } from '../src/integrations/webhook';
+import { createApp } from '../src/api/routes';
+
+async function startServer(): Promise<void> {
+  // ── 1. Initialize guard ───────────────────────────────────
+  const guard = await createChargebackGuard({
+    autoReply: true,
+    evidenceCollection: true,
+  });
+
+  // ── 2. Setup webhook handler ──────────────────────────────
+  const webhookHandler = new WebhookHandler();
+
+  // When a dispute is detected via Stripe webhook
+  webhookHandler.onDisputeDetected(async (dispute) => {
+    console.log(`🚨 Handling dispute: ${dispute.id}`);
+    await guard.handleDispute(dispute);
+  });
+
+  // When a dispute is resolved (won/lost)
+  webhookHandler.onDisputeResolved(async (disputeId, status, provider) => {
+    if (status === DisputeStatus.WON) {
+      console.log(`🏆 Dispute WON: ${disputeId}`);
+    } else if (status === DisputeStatus.LOST) {
+      console.log(`❌ Dispute LOST: ${disputeId}`);
+    }
+  });
+
+  // ── 3. Create Express app ─────────────────────────────────
+  const app = createApp(webhookHandler);
+
+  // Share guard instance with controllers
+  app.locals['chargebackGuard'] = guard;
+
+  // ── 4. Custom route: Register payment after Stripe charge ──
+  app.post('/charge-and-protect', express.json(), async (req, res) => {
+    try {
+      const {
+        orderId, amount, currency,
+        customerEmail, customerIp,
+        stripeChargeId,
+      } = req.body as {
+        orderId: string;
+        amount: number;
+        currency: string;
+        customerEmail: string;
+        customerIp?: string;
+        stripeChargeId: string;
+      };
+
+      // Register for protection
+      const result = await guard.registerPayment({
+        orderId,
+        amount,
+        currency,
+        customerEmail,
+        customerIp: customerIp ?? req.ip,
+        userAgent: req.headers['user-agent'],
+        transactionId: stripeChargeId,
+        provider: PaymentProvider.STRIPE,
+      });
+
+      res.json({
+        success: true,
+        message: 'Payment registered and protected',
+        ...result,
+      });
+    } catch (err) {
+      res.status(500).json({
+        success: false,
+        error: err instanceof Error ? err.message : 'Unknown error',
+      });
+    }
+  });
+
+  // ── 5. Start server ───────────────────────────────────────
+  const PORT = process.env.PORT ?? 3000;
+  const server = app.listen(PORT, () => {
+    console.log(`🛡️  ChargebackGuard API running at http://localhost:${PORT}`);
+    console.log(`   POST /api/v1/payments        — Register payment`);
+    console.log(`   GET  /api/v1/disputes         — List disputes`);
+    console.log(`   POST /api/v1/webhooks/stripe  — Stripe webhook`);
+    console.log(`   GET  /api/v1/analytics/stats  — Get stats`);
+    console.log(`   GET  /api/v1/health           — Health check`);
+  });
+
+  // ── 6. Graceful shutdown ──────────────────────────────────
+  const shutdown = async (): Promise<void> => {
+    console.log('\n🛑 Shutting down...');
+    server.close(async () => {
+      await guard.shutdown();
+      process.exit(0);
+    });
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+}
+
+startServer().catch(console.error);

package/package.json

@@ -0,0 +1,181 @@
+{
+  "name": "chargeback-guard",
+  "version": "2.0.0",
+  "description": "Ultra Pro chargeback protection system for e-commerce merchants. Automatically collects evidence, detects disputes, and submits AI-powered replies to banks via Stripe/PayPal webhooks.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "dev": "ts-node src/index.ts",
+    "dev:watch": "nodemon --exec ts-node src/index.ts",
+    "test": "jest --coverage",
+    "test:unit": "jest tests/unit --coverage",
+    "test:integration": "jest tests/integration",
+    "test:e2e": "jest tests/e2e",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write 'src/**/*.ts'",
+    "clean": "rimraf dist",
+    "prepublish": "npm run clean && npm run build",
+    "docs:generate": "typedoc --out docs/api src/index.ts",
+    "migrate": "ts-node src/database/migrate.ts",
+    "seed": "ts-node src/database/seed.ts",
+    "start": "node dist/index.js",
+    "start:pm2": "pm2 start ecosystem.config.js"
+  },
+  "keywords": [
+    "chargeback",
+    "fraud-detection",
+    "stripe",
+    "paypal",
+    "payment-protection",
+    "dispute-management",
+    "e-commerce",
+    "machine-learning",
+    "fintech",
+    "evidence-collection"
+  ],
+  "author": {
+    "name": "ChargebackGuard Team",
+    "email": "support@chargebackguard.io",
+    "url": "https://chargebackguard.io"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "dependencies": {
+    "stripe": "^14.0.0",
+    "@paypal/paypal-server-sdk": "^0.6.0",
+    "express": "^4.18.2",
+    "express-rate-limit": "^7.1.5",
+    "express-validator": "^7.0.1",
+    "cors": "^2.8.5",
+    "helmet": "^7.1.0",
+    "compression": "^1.7.4",
+    "morgan": "^1.10.0",
+    "dotenv": "^16.3.1",
+    "jsonwebtoken": "^9.0.2",
+    "bcryptjs": "^2.4.3",
+    "axios": "^1.6.2",
+    "uuid": "^9.0.1",
+    "date-fns": "^3.0.0",
+    "lodash": "^4.17.21",
+    "winston": "^3.11.0",
+    "winston-daily-rotate-file": "^4.7.1",
+    "ioredis": "^5.3.2",
+    "knex": "^3.1.0",
+    "pg": "^8.11.3",
+    "better-sqlite3": "^9.4.3",
+    "nodemailer": "^6.9.7",
+    "twilio": "^4.19.3",
+    "handlebars": "^4.7.8",
+    "node-cron": "^3.0.3",
+    "bull": "^4.12.0",
+    "socket.io": "^4.6.2",
+    "multer": "^1.4.5-lts.1",
+    "sharp": "^0.33.1",
+    "pdf-lib": "^1.17.1",
+    "archiver": "^6.0.1",
+    "zod": "^3.22.4",
+    "pino": "^8.17.2",
+    "pino-http": "^9.0.0",
+    "ms": "^2.1.3",
+    "p-retry": "^6.2.0",
+    "p-limit": "^5.0.0",
+    "node-cache": "^5.1.2",
+    "crypto-js": "^4.2.0",
+    "ip": "^2.0.1",
+    "geoip-lite": "^1.4.10",
+    "ua-parser-js": "^1.0.37"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.6",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "@types/compression": "^1.7.5",
+    "@types/morgan": "^1.9.9",
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/lodash": "^4.14.202",
+    "@types/nodemailer": "^6.4.14",
+    "@types/multer": "^1.4.11",
+    "@types/archiver": "^6.0.2",
+    "@types/uuid": "^9.0.7",
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/pg": "^8.10.9",
+    "@types/ms": "^0.7.34",
+    "@types/geoip-lite": "^1.4.4",
+    "@types/ua-parser-js": "^0.7.39",
+    "@types/jest": "^29.5.11",
+    "@types/supertest": "^6.0.2",
+    "typescript": "^5.3.3",
+    "ts-node": "^10.9.2",
+    "nodemon": "^3.0.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "supertest": "^6.3.4",
+    "eslint": "^8.56.0",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "prettier": "^3.1.1",
+    "rimraf": "^5.0.5",
+    "typedoc": "^0.25.6",
+    "husky": "^8.0.3",
+    "lint-staged": "^15.2.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "coverageDirectory": "coverage",
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/**/*.d.ts",
+      "!src/**/index.ts"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 75,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    },
+    "testMatch": [
+      "<rootDir>/tests/**/*.test.ts"
+    ],
+    "setupFilesAfterEnv": [
+      "<rootDir>/tests/setup.ts"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brah-timo/chargeback-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brah-timo/chargeback-guard/issues"
+  },
+  "homepage": "https://chargebackguard.io"
+}