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

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

Quick Start

Registration Flow

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: '[email protected]',
  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

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

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

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

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

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

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 for details.

RiskProfileClient

Customer risk profile management.

See Risk Profile SDK Documentation for details.

Migration from @cgs/geolocation-sdk

The unified SDK is fully backward compatible. See Migration Guide for details.

// 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
• Login Flow
• Transaction Verification
• Next.js Integration

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