vesant-sdk 1.0.8 → 1.1.1

package/README.md

@@ -1,13 +1,19 @@
 # Vesant Compliance SDK
 
-> TypeScript SDK for Vesant Compliance Platform - Geolocation Verification, Risk Profiling, and Compliance Orchestration
+> TypeScript SDK for Vesant Compliance Platform - Geolocation Verification, Risk Profiling, KYC, and Compliance Orchestration
 
 ## Features
 
 - **Geolocation Compliance** - IP verification, VPN/proxy detection, jurisdiction checks, device fingerprinting
-- **Risk Profiling** - Automated customer risk profile creation and management
+- **CipherText** - Encrypted device/location data collection with GPS auto-detection
+- **Risk Profiling** - Customer risk profile creation and management
+- **KYC** - Document verification, submission links, and status tracking
 - **Compliance Orchestration** - Unified registration, login, and transaction verification
-- **React Hooks** - Ready-to-use hooks for common compliance workflows
+- **Live Location Requests** - Request and capture GPS location from customers via SMS/email
+- **React Hooks** - Ready-to-use hooks for all compliance workflows
+- **Interceptors** - Request/response interceptors for logging, auth, and custom logic
+- **AbortController** - Cancel in-flight requests
+- **Structured Logging** - Pluggable logger interface
 - **Tree-Shakeable** - Import only what you need
 - **Type-Safe** - Full TypeScript support with detailed type definitions
 
@@ -31,7 +37,7 @@ import { ComplianceClient } from 'vesant-sdk';
 const sdk = new ComplianceClient({
   baseURL: process.env.VESANT_API_URL,
   tenantId: process.env.VESANT_TENANT_ID,
-  apiKey: process.env.VESANT_API_KEY
+  apiKey: process.env.VESANT_API_KEY,
 });
 ```
 
@@ -46,14 +52,13 @@ const result = await sdk.verifyAtRegistration({
   deviceFingerprint: {
     device_id: deviceId,
     user_agent: req.headers['user-agent'],
-    platform: 'web'
-  }
+    platform: 'web',
+  },
 });
 
 if (result.allowed) {
   console.log('Registration approved');
   console.log('Customer profile:', result.profile);
-  console.log('Risk category:', result.profile.risk_category);
 
   if (result.requiresKYC) {
     // Redirect to KYC flow
@@ -69,7 +74,7 @@ if (result.allowed) {
 const result = await sdk.verifyAtLogin({
   customerId: 'CUST-12345',
   ipAddress: req.ip,
-  deviceFingerprint: getDeviceFingerprint()
+  deviceFingerprint: getDeviceFingerprint(),
 });
 
 if (result.allowed) {
@@ -91,7 +96,7 @@ const result = await sdk.verifyAtTransaction({
   ipAddress: req.ip,
   amount: 5000,
   currency: 'USD',
-  transactionType: 'withdrawal'
+  transactionType: 'withdrawal',
 });
 
 if (result.allowed) {
@@ -103,6 +108,37 @@ if (result.allowed) {
 }
 ```
 
+### CipherText (Client-Side Device Fingerprinting)
+
+```typescript
+import { generateCipherText } from 'vesant-sdk/geolocation';
+
+// Collect device fingerprint + optional GPS on the client
+const result = await generateCipherText({
+  reason: 'login',
+  requestLocation: true,
+});
+
+// Send to your backend
+await fetch('/api/login', {
+  body: JSON.stringify({ email, password, cipherText: result.cipherText }),
+});
+```
+
+### Live Location Requests
+
+```typescript
+// Request a customer's live GPS location via SMS
+const result = await sdk.requestCustomerLocation({
+  customerId: 'CUST-12345',
+  channel: 'sms',
+  phone: '+1234567890',
+  reason: 'Transaction verification',
+});
+
+console.log('Share link sent:', result.shareLink);
+```
+
 ## Module-Specific Imports
 
 Import only what you need to reduce bundle size:
@@ -115,13 +151,13 @@ import { GeolocationClient } from 'vesant-sdk/geolocation';
 const geoClient = new GeolocationClient({
   baseURL: process.env.VESANT_API_URL,
   tenantId: process.env.VESANT_TENANT_ID,
-  apiKey: process.env.VESANT_API_KEY
+  apiKey: process.env.VESANT_API_KEY,
 });
 
 const verification = await geoClient.verifyIP({
   ip_address: '8.8.8.8',
   user_id: 'user-123',
-  event_type: 'login'
+  event_type: 'login',
 });
 
 console.log('Country:', verification.location.country_iso);
@@ -137,7 +173,7 @@ import { RiskProfileClient } from 'vesant-sdk/risk-profile';
 const riskClient = new RiskProfileClient({
   baseURL: process.env.VESANT_API_URL,
   tenantId: process.env.VESANT_TENANT_ID,
-  apiKey: process.env.VESANT_API_KEY
+  apiKey: process.env.VESANT_API_KEY,
 });
 
 const profile = await riskClient.getProfile('CUST-12345');
@@ -145,10 +181,33 @@ console.log('Risk score:', profile.risk_score);
 console.log('Risk category:', profile.risk_category);
 ```
 
+### KYC Only
+
+```typescript
+import { KycClient } from 'vesant-sdk/kyc';
+
+const kycClient = new KycClient({
+  baseURL: process.env.VESANT_API_URL,
+  tenantId: process.env.VESANT_TENANT_ID,
+  apiKey: process.env.VESANT_API_KEY,
+});
+
+const { link, kyc_id } = await kycClient.requestKycSubmitLink({
+  user_id: 'user-123',
+  redirect_url: 'https://yourapp.com/kyc-complete',
+});
+```
+
 ## React Hooks
 
 ```typescript
-import { useRegistration } from 'vesant-sdk/react';
+import {
+  useRegistration,
+  useLoginVerification,
+  useTransactionVerification,
+  useCipherText,
+  useCustomerProfile,
+} from 'vesant-sdk/react';
 
 function RegistrationForm() {
   const { verifyRegistration, loading, error } = useRegistration(sdk, {
@@ -158,7 +217,7 @@ function RegistrationForm() {
     },
     onBlocked: (result) => {
       alert(`Registration blocked: ${result.blockReasons.join(', ')}`);
-    }
+    },
   });
 
   const handleSubmit = async (formData) => {
@@ -166,7 +225,7 @@ function RegistrationForm() {
       customerId: formData.customerId,
       fullName: formData.fullName,
       emailAddress: formData.email,
-      ipAddress: await getClientIP()
+      ipAddress: await getClientIP(),
     });
   };
 
@@ -182,16 +241,58 @@ function RegistrationForm() {
 }
 ```
 
+## Interceptors
+
+```typescript
+const sdk = new ComplianceClient({
+  baseURL: process.env.VESANT_API_URL,
+  tenantId: process.env.VESANT_TENANT_ID,
+  apiKey: process.env.VESANT_API_KEY,
+  interceptors: [
+    {
+      onRequest: (url, options) => {
+        console.log(`[SDK] ${options.method || 'GET'} ${url}`);
+        return options;
+      },
+      onResponse: (url, data) => {
+        console.log(`[SDK] Response from ${url}`);
+        return data;
+      },
+      onError: (url, error) => {
+        console.error(`[SDK] Error from ${url}:`, error.message);
+      },
+    },
+  ],
+});
+```
+
+## AbortController
+
+```typescript
+const controller = new AbortController();
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+const result = await sdk.verifyAtLogin(
+  { customerId: 'CUST-12345', ipAddress: req.ip },
+  { signal: controller.signal }
+);
+```
+
 ## Configuration
 
 ```typescript
 interface ComplianceClientConfig {
-  baseURL: string;    // Vesant API Gateway URL
-  tenantId: string;         // Your tenant ID
-  apiKey: string;           // Your API key
-  timeout?: number;         // Request timeout in ms (default: 10000)
-  retries?: number;         // Retry attempts (default: 3)
-  debug?: boolean;          // Enable debug logging (default: false)
+  baseURL: string;              // Vesant API Gateway URL
+  tenantId: string;             // Your tenant ID
+  apiKey?: string;              // Your API key
+  timeout?: number;             // Request timeout in ms (default: 10000)
+  retries?: number;             // Retry attempts (default: 3)
+  debug?: boolean;              // Enable debug logging (default: false)
+  autoCreateProfiles?: boolean; // Auto-create risk profiles (default: true)
+  interceptors?: Interceptor[]; // Request/response interceptors
+  logger?: Logger;              // Custom logger instance
 }
 ```
 
@@ -204,39 +305,58 @@ interface ComplianceClientConfig {
 | `verifyAtRegistration(request)` | Verify new user registration |
 | `verifyAtLogin(request)` | Verify user login |
 | `verifyAtTransaction(request)` | Verify financial transaction |
+| `verifyEvent(request)` | Generic event verification |
 | `requestCustomerLocation(input)` | Request live GPS location from customer |
 | `getLocationRequest(requestId)` | Get location request status |
+| `listLocationRequests(filters)` | List location requests |
+| `cancelLocationRequest(requestId)` | Cancel a pending location request |
+| `updateCurrencyRates(rates)` | Update exchange rates for transaction risk |
 
 ### GeolocationClient
 
 | Method | Description |
 |--------|-------------|
 | `verifyIP(request)` | Verify IP address and check compliance |
+| `checkCompliance(countryISO)` | Check jurisdiction compliance |
 | `validateCipherText(cipherText, userId, eventType)` | Validate device fingerprint |
-| `listAlerts(filters)` | List compliance alerts |
-| `listJurisdictions()` | Get jurisdiction configurations |
+| `validateAndVerify(cipherText, ip, userId, eventType)` | Combined cipherText + IP verification |
+| `getGPSConfig()` | Get GPS requirement config per event type |
+| `createLocationRequest(request)` | Create a live location request |
+| `captureLocation(token, capture)` | Submit location capture (customer-facing) |
 
 ### RiskProfileClient
 
 | Method | Description |
 |--------|-------------|
 | `createProfile(request)` | Create customer risk profile |
-| `getProfile(customerId)` | Get profile by customer ID |
+| `getProfile(customerId)` | Get profile by customer ID (exact match) |
 | `updateProfile(profileId, updates)` | Update customer profile |
-| `getDashboardMetrics()` | Get risk dashboard metrics |
+| `getOrCreateProfile(customerId, request)` | Idempotent get-or-create |
+
+### KycClient
+
+| Method | Description |
+|--------|-------------|
+| `requestKycSubmitLink(request)` | Generate a KYC submission link |
+| `checkKycStatus(request)` | Check KYC verification status |
+| `submitVerification(request)` | Submit document verification |
+| `listKycRequests(filters)` | List KYC requests |
+| `getPreferences()` | Get KYC preferences |
+| `listAlerts(filters)` | List KYC alerts |
 
 ## Documentation
 
 For detailed documentation, see the [docs](./docs) directory:
 
-- [Installation](./docs/getting-started/installation.md)
 - [Quick Start](./docs/getting-started/quick-start.md)
 - [Configuration](./docs/getting-started/configuration.md)
+- [Authentication](./docs/getting-started/authentication.md)
 - [Registration Flow](./docs/guides/registration.md)
-- [Login Flow](./docs/guides/login.md)
 - [Transaction Verification](./docs/guides/transactions.md)
+- [Next.js Integration](./docs/guides/nextjs.md)
 - [React Hooks](./docs/react-hooks/overview.md)
-- [Error Handling](./docs/advanced/error-handling.md)
+- [Error Handling & Types](./docs/advanced/types.md)
+- [Security](./docs/advanced/security.md)
 
 ## License
 
@@ -244,4 +364,4 @@ MIT
 
 ## Support
 
-For support, contact your Vesant account representative or visit the [support portal](https://support.vesant.ai).
+For support, contact your Vesant account representative.