> For the complete documentation index, see [llms.txt](https://docs.vesant.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vesant.ai/overview/readme.md).

# Introduction

## Introduction

The **Vesant Compliance SDK** is a unified TypeScript SDK for casino platforms and gaming/fintech applications to integrate comprehensive compliance capabilities. It provides real-time verification for registration, login, and transactions while automatically managing customer risk profiles.

### Key Features

* **Unified Compliance Orchestration** - Single entry point for all compliance checks
* **Real-time Geolocation Verification** - IP verification, VPN/proxy detection, jurisdiction compliance
* **Automated Risk Profiling** - Customer risk scoring with KYC, AML, fraud, and geolocation factors
* **Fraud Event Scoring** - Send tenant fraud events and consume risk decisions for custom action policies
* **Automated Decision Recording** - Record compliance decisions and apply customer labels *(coming soon)*
* **Webhook Handling** - Typed event handlers with signature verification and framework middleware
* **Device Fingerprinting** - Track and trust customer devices
* **Production Resilience** - Circuit breaker, rate limit tracking, request IDs, idempotency
* **React Hooks** - Ready-to-use hooks for common workflows
* **Type Safety** - Full TypeScript support with detailed type definitions
* **Tree-Shakeable** - Stable APIs use subpath imports from `vesant-sdk` (for example `vesant-sdk/geolocation`, `vesant-sdk/webhooks`). The experimental `FraudClient` lives in a separate scoped package, `@vesant-sdk/fraud`, which requires its own `npm install`.

### Use Cases

| Scenario                   | SDK Method                                   | Description                                                                                                                                             |
| -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New user registration      | `verifyAtRegistration()`                     | Verify location, create risk profile, check compliance                                                                                                  |
| User login                 | `verifyAtLogin()`                            | Verify IP, check for suspicious activity, update profile                                                                                                |
| Financial transaction      | `verifyAtTransaction()`                      | Risk assessment based on amount, location, and history                                                                                                  |
| Fraud event scoring        | `scoreEvent()`                               | Score an account event, order or chargeback and receive the risk decision and signals                                                                   |
| Record a money movement    | `createTransaction()` / `submitWithdrawal()` | Report a deposit, withdrawal, transfer or wager for transaction monitoring, tax and fraud scoring; the fraud decision arrives on `fraud.alert.callback` |
| Periodic checks            | `validateCipherText()`                       | Validate encrypted location data from frontend                                                                                                          |
| Live location request      | `requestCustomerLocation()`                  | Request real-time GPS location from customer                                                                                                            |
| Start KYC verification     | `requestKycSubmitLink()`                     | Generate a KYC submission URL for document upload                                                                                                       |
| Check KYC status           | `checkKycStatus()`                           | Poll for KYC verification result after submission                                                                                                       |
| Re-verify a returning user | `createEventBasedFaceVerificationSession()`  | Face check for high-risk events, completed in the built-in modal                                                                                        |
| Handle webhooks            | `WebhookHandler.handle()`                    | Process webhook events with signature verification                                                                                                      |

### Quick Example

```typescript
import { ComplianceClient } from 'vesant-sdk';

// Initialize the SDK
const sdk = new ComplianceClient({
  baseURL: 'https://api.yourplatform.com',
  tenantId: 'your-tenant-id',
  apiKey: 'your-api-key'
});

// Verify user at registration
const result = await sdk.verifyAtRegistration({
  customerId: '550e8400-e29b-41d4-a716-446655440000',
  fullName: 'John Doe',
  emailAddress: 'john@example.com',
  ipAddress: '192.168.1.1'
});

if (result.allowed) {
  console.log('Registration allowed');
  console.log('Risk category:', result.profile.risk_category);
} else {
  console.log('Blocked:', result.blockReasons);
}
```

Fraud scoring quick example (install the scoped package; it is not bundled inside `vesant-sdk`):

```bash
npm install @vesant-sdk/fraud
```

```typescript
import { FraudClient } from '@vesant-sdk/fraud';

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

const scored = await fraud.scoreEvent({
  customer_id: '550e8400-e29b-41d4-a716-446655440000',
  user_reference: '550e8400-e29b-41d4-a716-446655440000',
  event_type: '$login',
  ip_address: '192.168.1.1',
});

console.log(scored.data.decision, scored.data.risk_level);
```

### Requirements

* Node.js 16+ or modern browser
* TypeScript 4.7+ (recommended)
* React 18+ (for hooks, optional)

### Getting Help

For support, contact your Vesant account representative or visit the [support portal](https://support.vesant.ai).

### License

MIT License