> 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`). Experimental clients (`FraudClient`, `TransactionClient`) live in separate scoped packages: `@vesant-sdk/fraud`, `@vesant-sdk/transaction` — each 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 a fraud event and receive risk decision/signals    |
| Bulk fraud scoring     | `scoreEventsBulk()`         | Score multiple events in one request                     |
| 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        |
| 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',
  sift_user_id: '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