cgs-compliance-sdk 2.0.0

package/README.md

@@ -0,0 +1,278 @@
+# 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)