# cgs-compliance-sdk - Unified CGS Compliance SDK

> Comprehensive TypeScript SDK for CGS Compliance Platform - Geolocation, Risk Profiling, and Compliance Orchestration

## Features

- **Geolocation Compliance** - IP verification, VPN detection, jurisdiction checks, device fingerprinting
- **Risk Profiling** - Automated customer risk profile creation and management
- **Compliance Orchestration** - Unified registration, login, and transaction verification
- **React Hooks** - Ready-to-use hooks for common compliance workflows
- **Tree-Shakeable** - Import only what you need
- **Type-Safe** - Full TypeScript support with detailed type definitions

## Installation

```bash
npm install cgs-compliance-sdk
# or
yarn add cgs-compliance-sdk
# or
pnpm add cgs-compliance-sdk
```

## Quick Start

### Registration Flow

```typescript
import { ComplianceClient } from 'cgs-compliance-sdk';

const sdk = new ComplianceClient({
  apiGatewayURL: 'https://api.yourplatform.com',
  tenantId: 'your-casino-id',
  apiKey: 'your-api-key',
  autoCreateProfiles: true
});

// Verify registration with automatic profile creation
const result = await sdk.verifyAtRegistration({
  customerId: 'CUST-12345',
  fullName: 'John Doe',
  emailAddress: 'john@example.com',
  ipAddress: req.ip,
  deviceFingerprint: {
    device_id: deviceId,
    user_agent: req.headers['user-agent'],
    platform: 'web'
  }
});

if (result.allowed) {
  // Registration approved
  console.log('Customer profile created:', result.profile);
  console.log('Risk score:', result.profile.risk_score);

  if (result.requiresKYC) {
    // Redirect to KYC flow
  }
} else {
  // Registration blocked
  console.log('Blocked reasons:', result.blockReasons);
}
```

### Login Verification

```typescript
const loginResult = await sdk.verifyAtLogin({
  customerId: 'CUST-12345',
  ipAddress: req.ip,
  deviceFingerprint: getDeviceFingerprint()
});

if (loginResult.allowed) {
  // Allow login
  if (loginResult.requiresStepUp) {
    // Trigger additional verification (MFA, etc.)
  }
} else {
  // Block login
  console.log('Blocked:', loginResult.blockReasons);
}
```

### Transaction Verification

```typescript
const txResult = await sdk.verifyAtTransaction({
  customerId: 'CUST-12345',
  ipAddress: req.ip,
  amount: 5000,
  currency: 'USD',
  transactionType: 'withdrawal',
  deviceFingerprint: getDeviceFingerprint()
});

if (txResult.allowed) {
  // Process transaction
} else if (txResult.requiresApproval) {
  // Queue for manual review
} else {
  // Block transaction
  console.log('Blocked:', txResult.blockReasons);
}
```

## Module-Specific Imports

### Geolocation Only

```typescript
import { GeolocationClient } from 'cgs-compliance-sdk/geolocation';

const geoClient = new GeolocationClient({
  baseURL: 'https://api.yourplatform.com',
  tenantId: 'your-casino-id',
  apiKey: 'your-api-key'
});

const verification = await geoClient.verifyIP({
  ip_address: '8.8.8.8',
  user_id: 'user-123',
  event_type: 'login'
});
```

### Risk Profile Only

```typescript
import { RiskProfileClient } from 'cgs-compliance-sdk/risk-profile';

const riskClient = new RiskProfileClient({
  baseURL: 'https://api.yourplatform.com',
  tenantId: 'your-casino-id',
  apiKey: 'your-api-key'
});

const profile = await riskClient.getProfile('CUST-12345');
console.log('Risk category:', profile.risk_category);
```

## React Hooks

```typescript
import { useRegistration, useCustomerProfile } from 'cgs-compliance-sdk';

function RegistrationForm() {
  const { verifyRegistration, loading, error } = useRegistration(sdk, {
    onSuccess: (result) => {
      console.log('Registration approved!', result.profile);
      navigate('/dashboard');
    },
    onBlocked: (result) => {
      alert(`Registration blocked: ${result.blockReasons.join(', ')}`);
    }
  });

  const handleSubmit = async (formData) => {
    await verifyRegistration({
      customerId: formData.customerId,
      fullName: formData.fullName,
      emailAddress: formData.email,
      ipAddress: await getClientIP(),
      deviceFingerprint: getDeviceFingerprint()
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Your form fields */}
      <button disabled={loading}>
        {loading ? 'Verifying...' : 'Register'}
      </button>
      {error && <ErrorMessage>{error.message}</ErrorMessage>}
    </form>
  );
}
```

## API Documentation

### ComplianceClient

Main orchestration client that combines geolocation and risk profiling.

#### Configuration

```typescript
interface CGSConfig {
  geolocationServiceURL: string;
  riskProfileServiceURL: string;
  tenantId: string;
  apiKey?: string;
  timeout?: number;
  retries?: number;
  debug?: boolean;
  autoCreateProfiles?: boolean;
}
```

#### Methods

- `verifyAtRegistration(request)` - Complete registration verification with profile creation
- `verifyAtLogin(request)` - Login verification with profile update
- `verifyAtTransaction(request)` - Transaction verification with amount-based risk
- `verifyEvent(request)` - Generic event verification

### GeolocationClient

IP verification, jurisdiction checks, and device fingerprinting.

See [Geolocation SDK Documentation](./docs/geolocation.md) for details.

### RiskProfileClient

Customer risk profile management.

See [Risk Profile SDK Documentation](./docs/risk-profile.md) for details.

## Migration from @cgs/geolocation-sdk

The unified SDK is fully backward compatible. See [Migration Guide](./MIGRATION.md) for details.

```typescript
// Before (@cgs/geolocation-sdk v1.x)
import { GeolocationClient } from '@cgs/geolocation-sdk';

// After (cgs-compliance-sdk v2.x) - Same API
import { GeolocationClient } from 'cgs-compliance-sdk/geolocation';
```

## Examples

- [Registration Flow](./examples/registration-flow.tsx)
- [Login Flow](./examples/login-flow.tsx)
- [Transaction Verification](./examples/transaction-flow.tsx)
- [Next.js Integration](./examples/next-js-casino/)

## Architecture Overview

### API Gateway Pattern

**IMPORTANT**: All SDK requests go through the API Gateway. Direct access to individual services is not permitted for third parties.

```
Casino Platform → CGS SDK → API Gateway → Backend Services
                                ↓
                    ┌───────────┴───────────┐
                    ↓                       ↓
            Geolocation Service    Risk Profile Service
                    ↓                       ↓
                   Kafka Event Bus
                    ↓
        ┌───────────┼───────────┬───────────┐
        ↓           ↓           ↓           ↓
   KYC Service  AML Service  Fraud Service  Analytics
        ↓           ↓           ↓
   All publish events consumed by Risk Profile Service
```

### Event-Driven Profile Updates

Customer risk profiles are automatically updated via Kafka events from all compliance services:

**Geolocation Events** → Updates location, compliance status, geo risk factor
**KYC Events** → Updates KYC status, identity verification, KYC risk factor
**AML Events** → Updates watchlist matches, PEP status, sanctions, AML risk factor
**Fraud Events** → Updates flagged transactions, fraud risk factor

This ensures customer profiles always reflect the latest compliance data from all sources.

## License

MIT

## Support

For issues and questions, please visit [GitHub Issues](https://github.com/botcalm-compliance/cgs-server/issues)