chargeback-guard 2.0.0

package/docs/architecture.md

@@ -0,0 +1,281 @@
+# chargeback-guard — Architecture
+
+This document describes the internal design of chargeback-guard v2.
+
+---
+
+## High-Level Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       Your Application                          │
+│                                                                 │
+│   registerPayment()          handleDispute()                    │
+│         │                         │                             │
+└─────────┼─────────────────────────┼─────────────────────────────┘
+          │                         │
+          ▼                         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     ChargebackGuard Core                        │
+│                                                                 │
+│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐   │
+│  │   Evidence   │   │   Dispute    │   │  Fraud Detection │   │
+│  │  Collection  │   │  Analysis    │   │  (AI / ML)       │   │
+│  └──────┬───────┘   └──────┬───────┘   └────────┬─────────┘   │
+│         │                  │                      │             │
+│         └──────────────────┴──────────────────────┘             │
+│                            │                                    │
+│                   ┌────────▼────────┐                           │
+│                   │  Response Engine│  ←── AI reply generation  │
+│                   └────────┬────────┘                           │
+│                            │                                    │
+│              ┌─────────────┼──────────────┐                     │
+│              ▼             ▼              ▼                     │
+│        Stripe API     PayPal API     Square API                 │
+└─────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Infrastructure Layer                        │
+│                                                                 │
+│   Database (SQLite/PG/MySQL)   Redis Cache   Notifications      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Module Structure
+
+```
+src/
+├── core/
+│   ├── chargebackGuard.ts    # Main orchestrator class
+│   ├── eventEmitter.ts       # Typed event bus
+│   └── lifecycle.ts          # Startup / shutdown hooks
+│
+├── evidence/
+│   ├── collector.ts          # Collects device, geo, behavior signals
+│   ├── validator.ts          # Validates evidence completeness & quality
+│   └── storage.ts            # Persists/retrieves evidence bundles
+│
+├── dispute/
+│   ├── detector.ts           # Parses incoming dispute webhooks
+│   ├── analyzer.ts           # Selects response strategy per reason code
+│   └── responseEngine.ts     # Builds & submits evidence reply to provider
+│
+├── ai/
+│   └── fraudDetection.ts     # AI-powered fraud score & reply generation
+│
+├── integrations/
+│   ├── stripe.ts             # Stripe Disputes API wrapper
+│   ├── paypal.ts             # PayPal Disputes API wrapper
+│   └── square.ts             # Square Disputes API wrapper
+│
+├── database/
+│   └── schema.ts             # Database schema manager + query helpers
+│
+├── notifications/
+│   ├── email.ts              # SMTP email sender
+│   ├── sms.ts                # Twilio SMS sender
+│   ├── webhook.ts            # Outbound webhook dispatcher
+│   └── inApp.ts              # Notification service coordinator
+│
+├── security/
+│   ├── encryption.ts         # AES-256 encryption for sensitive fields
+│   ├── rateLimit.ts          # Per-IP and per-key rate limiting
+│   └── auth.ts               # JWT auth middleware
+│
+├── analytics/
+│   └── stats.ts              # Aggregation queries for ProtectionStats
+│
+├── api/
+│   └── router.ts             # Optional Express/Fastify API server
+│
+├── types/
+│   └── index.ts              # All interfaces, enums, and shared types
+│
+├── config.ts                 # Environment variable loading
+├── utils/
+│   └── logger.ts             # Structured logger
+└── index.ts                  # Public API surface
+```
+
+---
+
+## Data Flow: Payment Registration
+
+```
+registerPayment(paymentData)
+        │
+        ├── 1. validatePaymentData()        — required fields, amount > 0
+        │
+        ├── 2. FraudDetection.preCheck()    — AI trust score (0–100)
+        │         └── riskLevel assigned from score
+        │
+        ├── 3. EvidenceCollector.collect()  — device FP, geo, behavior
+        │
+        ├── 4. EvidenceStorage.save()       — persist bundle, indexed by orderId
+        │
+        ├── 5. emit('payment:registered')
+        │
+        └── 6. return RegistrationResult { trustScore, riskLevel, ... }
+```
+
+---
+
+## Data Flow: Dispute Handling
+
+```
+handleDispute(dispute)
+        │
+        ├── 1. DisputeDetector.parse()       — normalize & validate dispute
+        │
+        ├── 2. EvidenceStorage.getByOrderId()— fetch pre-collected evidence
+        │
+        ├── 3. DisputeAnalyzer.analyze()     — strategy per reason code
+        │         ├── 'product_not_received' → delivery proof emphasis
+        │         ├── 'unauthorized_transaction' → device FP + geo
+        │         └── 'fraudulent' → full AI analysis
+        │
+        ├── 4. FraudDetection.analyze()      — AI confidence score
+        │
+        ├── 5a. confidence ≥ threshold AND autoReply = true
+        │         └── ResponseEngine.submit() → provider API
+        │               └── actionTaken = 'auto-reply_submitted'
+        │
+        ├── 5b. confidence < threshold
+        │         └── actionTaken = 'manual_review_required'
+        │               └── emit('dispute:detected') for notification
+        │
+        ├── 6. updateDisputeRecord()         — persist outcome
+        │
+        └── 7. return DisputeHandlingResult
+```
+
+---
+
+## Evidence Bundle
+
+The evidence bundle assembled per order contains:
+
+| Evidence Type | Source | Description |
+|---|---|---|
+| `delivery_proof` | Metadata field / shipping API | Tracking number, carrier, delivered timestamp |
+| `device_fingerprint` | Client SDK / metadata | Browser fingerprint, device ID |
+| `geolocation` | IP geolocation | Country, city, ISP |
+| `customer_communication` | CRM integration | Email thread, support tickets |
+| `transaction_log` | Payment provider | All charges on the card |
+| `behavior_analysis` | Analytics | Session duration, page views, cart events |
+| `customer_history` | Your database | Previous orders, dispute history |
+| `email_confirmation` | Email service | Order confirmation email sent timestamp |
+| `payment_log` | Provider | Auth + capture log |
+| `browser_screenshot` | Optional | Checkout page screenshot at purchase time |
+
+---
+
+## AI Fraud Detection
+
+The `FraudDetection` module uses a multi-signal scoring model:
+
+```
+trustScore = weighted_average([
+  customerHistory:    30%,   // past orders, first-time buyer, return rate
+  deviceFingerprint:  20%,   // known device vs new device
+  geolocation:        15%,   // IP country matches billing country
+  behaviorAnalysis:   15%,   // time on site, scrolling, clicks
+  transactionPattern: 20%,   // amount vs average, velocity
+])
+```
+
+When `ai.apiKey` is configured, an LLM call supplements the heuristic score with natural language reasoning. The LLM also generates the evidence reply text sent to the bank.
+
+---
+
+## Database Schema
+
+Four core tables:
+
+### `payments`
+| Column | Type | Description |
+|---|---|---|
+| `id` | TEXT PK | Internal UUID |
+| `order_id` | TEXT UNIQUE | Your order ID |
+| `customer_id` | TEXT | Your customer ID |
+| `amount` | INTEGER | Cents |
+| `currency` | TEXT | ISO 4217 |
+| `provider` | TEXT | Payment provider |
+| `transaction_id` | TEXT | Provider transaction ID |
+| `trust_score` | REAL | 0–100 |
+| `risk_level` | TEXT | Risk enum value |
+| `metadata` | JSON | Raw payment metadata |
+| `created_at` | INTEGER | Unix ms |
+
+### `evidence_bundles`
+| Column | Type | Description |
+|---|---|---|
+| `id` | TEXT PK | Bundle UUID |
+| `order_id` | TEXT FK | Links to `payments.order_id` |
+| `evidence_types` | JSON | Array of collected evidence types |
+| `data` | JSON (encrypted) | Evidence payload |
+| `collected_at` | INTEGER | Unix ms |
+
+### `disputes`
+| Column | Type | Description |
+|---|---|---|
+| `id` | TEXT PK | Provider dispute ID |
+| `order_id` | TEXT FK | Links to `payments.order_id` |
+| `amount` | INTEGER | Disputed amount |
+| `reason` | TEXT | DisputeReason value |
+| `status` | TEXT | DisputeStatus value |
+| `action_taken` | TEXT | What ChargebackGuard did |
+| `reply_submitted` | INTEGER | 0 or 1 |
+| `confidence` | REAL | AI confidence |
+| `due_by` | INTEGER | Evidence deadline (Unix ms) |
+| `created_at` | INTEGER | Unix ms |
+| `updated_at` | INTEGER | Unix ms |
+
+### `notifications`
+| Column | Type | Description |
+|---|---|---|
+| `id` | TEXT PK | Notification UUID |
+| `event_type` | TEXT | NotificationEvent value |
+| `channel` | TEXT | Email / SMS / webhook |
+| `payload` | JSON | Event payload snapshot |
+| `status` | TEXT | `pending` / `sent` / `failed` |
+| `sent_at` | INTEGER | Unix ms |
+
+---
+
+## Lifecycle Hooks
+
+`ChargebackGuard.lifecycle` is a `LifecycleManager` that manages startup and shutdown phases:
+
+```typescript
+guard.lifecycle.on('initialized', () => console.log('Ready'));
+guard.lifecycle.on('shutting_down', () => console.log('Draining...'));
+guard.lifecycle.on('shutdown', () => console.log('Stopped'));
+```
+
+### Startup sequence (in order)
+1. Load and validate configuration
+2. Connect to database, run migrations
+3. Connect to Redis (if configured)
+4. Start notification services
+5. Register health checkers
+6. Mark lifecycle as `initialized`
+
+### Shutdown sequence
+1. Stop accepting new `registerPayment()` / `handleDispute()` calls
+2. Flush in-flight evidence and reply submissions
+3. Close database connections
+4. Disconnect Redis
+5. Emit `shutdown` event
+
+---
+
+## Security Considerations
+
+- **Webhook signature verification** — always verify `stripe-signature` or `PAYPAL-TRANSMISSION-SIG` before calling `handleDispute()`.
+- **Evidence encryption** — evidence bundles are AES-256 encrypted at rest when `security.encryptionKey` is set.
+- **Rate limiting** — the optional HTTP server enforces per-IP rate limits to prevent replay attacks.
+- **PII handling** — customer email and IP are hashed before logging; raw values stored in encrypted evidence only.

package/docs/configuration.md

@@ -0,0 +1,292 @@
+# chargeback-guard — Configuration Reference
+
+---
+
+## Environment Variables
+
+chargeback-guard uses `dotenv` and reads configuration from environment variables. Create a `.env` file at your project root:
+
+```dotenv
+# ── Application ────────────────────────────────────────────────
+APP_NAME=ChargebackGuard
+APP_VERSION=2.0.0
+NODE_ENV=production           # development | staging | production
+PORT=3000
+APP_URL=https://api.mystore.com
+LOG_LEVEL=info                # debug | info | warn | error
+
+# ── Payment Provider ───────────────────────────────────────────
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+PAYPAL_CLIENT_ID=...
+PAYPAL_CLIENT_SECRET=...
+
+# ── Database ───────────────────────────────────────────────────
+DATABASE_TYPE=sqlite           # sqlite | postgresql | mysql
+DATABASE_URL=sqlite://./data/chargeback-guard.db
+DATABASE_POOL_MIN=2
+DATABASE_POOL_MAX=10
+DATABASE_DEBUG=false
+
+# ── Redis (optional) ──────────────────────────────────────────
+REDIS_URL=redis://localhost:6379
+REDIS_PASSWORD=
+REDIS_DB=0
+CACHE_TTL=3600
+
+# ── AI / Fraud Detection ──────────────────────────────────────
+OPENAI_API_KEY=sk-...
+AI_MODEL=gpt-4o-mini
+AI_CONFIDENCE_THRESHOLD=0.75
+FRAUD_SCORE_THRESHOLD=0.65
+
+# ── Notifications: Email ──────────────────────────────────────
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=apikey
+SMTP_PASS=SG.xxx
+EMAIL_FROM_NAME=ChargebackGuard Alerts
+EMAIL_FROM_ADDRESS=alerts@mystore.com
+ALERT_EMAIL=ops@mystore.com
+
+# ── Notifications: SMS ────────────────────────────────────────
+TWILIO_ACCOUNT_SID=ACxxx
+TWILIO_AUTH_TOKEN=xxx
+TWILIO_FROM_NUMBER=+15551234567
+ALERT_PHONE=+15557654321
+
+# ── Security ──────────────────────────────────────────────────
+API_KEY=your-internal-api-key
+JWT_SECRET=your-jwt-secret
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW=900         # seconds
+ENCRYPTION_KEY=32-byte-hex
+
+# ── Subscription ──────────────────────────────────────────────
+SUBSCRIPTION_PLAN=pro         # free | starter | pro | enterprise | custom
+MAX_PAYMENTS_PER_MONTH=50000
+MAX_DISPUTES_PER_MONTH=5000
+```
+
+---
+
+## Programmatic Configuration
+
+Options passed to `createChargebackGuard()` (or `new ChargebackGuard()`) override environment variables:
+
+```typescript
+import { createChargebackGuard } from 'chargeback-guard';
+
+const guard = await createChargebackGuard({
+  apiKey: process.env.STRIPE_SECRET_KEY!,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+  environment: 'production',
+
+  autoReply: true,
+  evidenceCollection: true,
+
+  database: {
+    type: 'postgresql',
+    url: process.env.DATABASE_URL!,
+    poolMin: 2,
+    poolMax: 20,
+    debug: false,
+  },
+
+  redis: {
+    url: process.env.REDIS_URL!,
+    ttl: 7200,
+  },
+
+  notifications: {
+    channels: ['email', 'webhook'],
+    email: {
+      host: 'smtp.sendgrid.net',
+      port: 587,
+      secure: false,
+      user: 'apikey',
+      pass: process.env.SMTP_PASS!,
+      fromName: 'ChargebackGuard',
+      fromAddress: 'alerts@mystore.com',
+    },
+    webhooks: [
+      { url: 'https://hooks.slack.com/services/...', events: ['dispute:detected', 'dispute:won'] },
+    ],
+  },
+
+  ai: {
+    model: 'gpt-4o-mini',
+    apiKey: process.env.OPENAI_API_KEY!,
+    confidenceThreshold: 0.80,
+    fraudScoreThreshold: 0.60,
+  },
+
+  security: {
+    encryptionKey: process.env.ENCRYPTION_KEY!,
+    jwtSecret: process.env.JWT_SECRET!,
+    rateLimitMax: 100,
+    rateLimitWindowSeconds: 900,
+  },
+});
+```
+
+---
+
+## `ChargebackGuardConfig`
+
+Top-level config object passed to the constructor.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | required | Stripe secret key (or provider API key) |
+| `webhookSecret` | `string?` | — | Webhook signing secret for verification |
+| `environment` | `'development' \| 'staging' \| 'production'` | `'development'` | Controls logging verbosity and safety checks |
+| `autoReply` | `boolean` | `true` | Automatically submit replies to the payment provider |
+| `evidenceCollection` | `boolean` | `true` | Collect device/behavior evidence on `registerPayment()` |
+| `database` | `DatabaseConfig` | SQLite at `./data/...` | Database connection settings |
+| `redis` | `RedisConfig?` | — | Redis for caching (optional) |
+| `notifications` | `NotificationConfig?` | — | Email / SMS / webhook alerts |
+| `security` | `SecurityConfig?` | — | Encryption and rate-limiting |
+| `ai` | `AIConfig?` | — | AI/fraud-detection model settings |
+| `billing` | `BillingConfig?` | — | Subscription plan and usage limits |
+
+---
+
+## Database Configuration
+
+### SQLite (default)
+
+```typescript
+database: {
+  type: 'sqlite',
+  url: 'sqlite://./data/chargeback-guard.db',
+}
+```
+
+No extra dependencies needed. Suitable for single-instance deployments up to ~10 k disputes/month.
+
+### PostgreSQL
+
+```typescript
+database: {
+  type: 'postgresql',
+  url: 'postgresql://user:pass@host:5432/chargebacks',
+  poolMin: 2,
+  poolMax: 20,
+}
+```
+
+Requires `pg` installed: `npm install pg`.
+
+### MySQL
+
+```typescript
+database: {
+  type: 'mysql',
+  url: 'mysql://user:pass@host:3306/chargebacks',
+}
+```
+
+Requires `mysql2` installed: `npm install mysql2`.
+
+---
+
+## Notification Configuration
+
+### Email
+
+```typescript
+notifications: {
+  channels: ['email'],
+  email: {
+    host: 'smtp.sendgrid.net',
+    port: 587,
+    secure: false,
+    user: 'apikey',
+    pass: 'SG.xxx',
+    fromName: 'ChargebackGuard Alerts',
+    fromAddress: 'alerts@mystore.com',
+  },
+}
+```
+
+### Outbound Webhooks
+
+```typescript
+notifications: {
+  channels: ['webhook'],
+  webhooks: [
+    {
+      url: 'https://hooks.slack.com/services/...',
+      events: ['dispute:detected', 'dispute:won', 'dispute:lost'],
+    },
+    {
+      url: 'https://yourapp.com/internal/chargeback-hook',
+      secret: 'hmac-signing-secret',   // HMAC-SHA256 signature header
+    },
+  ],
+}
+```
+
+### SMS (Twilio)
+
+```typescript
+notifications: {
+  channels: ['sms'],
+  sms: {
+    accountSid: process.env.TWILIO_ACCOUNT_SID!,
+    authToken:  process.env.TWILIO_AUTH_TOKEN!,
+    fromNumber: '+15551234567',
+    toNumber:   '+15557654321',
+  },
+}
+```
+
+---
+
+## AI / Fraud Detection Configuration
+
+```typescript
+ai: {
+  model: 'gpt-4o-mini',                   // OpenAI model for dispute reply generation
+  apiKey: process.env.OPENAI_API_KEY!,
+  confidenceThreshold: 0.75,              // Minimum AI confidence to auto-reply (0–1)
+  fraudScoreThreshold: 0.65,              // Score above which to flag as high-risk
+}
+```
+
+When `autoReply: true` and AI confidence is below `confidenceThreshold`, the dispute is routed to `actionTaken: 'manual_review_required'` instead of being auto-submitted.
+
+---
+
+## Security Configuration
+
+```typescript
+security: {
+  encryptionKey: '32-byte-hex-string',   // AES-256 key for sensitive data at rest
+  jwtSecret: 'your-jwt-secret',          // API authentication (if using built-in server)
+  rateLimitMax: 100,                     // Max requests per window
+  rateLimitWindowSeconds: 900,           // 15-minute window
+}
+```
+
+---
+
+## Subscription Plans
+
+| Plan | Max Payments/mo | Max Disputes/mo | AI Auto-Reply |
+|---|---|---|---|
+| `free` | 500 | 50 | ✗ |
+| `starter` | 5 000 | 500 | ✓ |
+| `pro` | 50 000 | 5 000 | ✓ |
+| `enterprise` | Unlimited | Unlimited | ✓ |
+| `custom` | Negotiated | Negotiated | ✓ |
+
+```typescript
+billing: {
+  plan: 'pro',
+  maxPaymentsPerMonth: 50_000,
+  maxDisputesPerMonth: 5_000,
+}
+```