vesant-sdk 1.0.8 → 1.1.0

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.

package/dist/client-B7YzKVEm.d.mts

@@ -0,0 +1,52 @@
+import { a as RequiredBaseClientConfig, L as Logger, B as BaseClientConfig, R as RequestOptions } from './types-DBGM-bFB.mjs';
+
+/**
+ * Base HTTP client for all CGS SDK clients
+ *
+ * Provides common functionality:
+ * - Request/response handling
+ * - Error handling
+ * - Retry logic with exponential backoff
+ * - Timeout management
+ * - Debug logging
+ */
+
+declare abstract class BaseClient {
+    protected config: RequiredBaseClientConfig;
+    protected logger: Logger;
+    private interceptors;
+    constructor(config: BaseClientConfig);
+    /**
+     * Make an HTTP request with timeout and error handling
+     */
+    protected request<T>(endpoint: string, options?: RequestInit, serviceURL?: string, requestOptions?: RequestOptions): Promise<T>;
+    /**
+     * Make an HTTP request with retry logic
+     */
+    protected requestWithRetry<T>(endpoint: string, options?: RequestInit, serviceURL?: string, retries?: number, requestOptions?: RequestOptions): Promise<T>;
+    /**
+     * Handle error responses from API
+     */
+    protected handleErrorResponse(status: number, data: Record<string, unknown>): never;
+    /**
+     * Build query string from parameters
+     */
+    protected buildQueryString(params: Record<string, unknown>): string;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<BaseClientConfig>): void;
+    /**
+     * Get current configuration (readonly)
+     */
+    getConfig(): Readonly<BaseClientConfig>;
+    /**
+     * Health check endpoint
+     */
+    healthCheck(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+}
+
+export { BaseClient as B };

package/dist/client-BaNLT2Df.d.ts

@@ -0,0 +1,52 @@
+import { a as RequiredBaseClientConfig, L as Logger, B as BaseClientConfig, R as RequestOptions } from './types-DBGM-bFB.js';
+
+/**
+ * Base HTTP client for all CGS SDK clients
+ *
+ * Provides common functionality:
+ * - Request/response handling
+ * - Error handling
+ * - Retry logic with exponential backoff
+ * - Timeout management
+ * - Debug logging
+ */
+
+declare abstract class BaseClient {
+    protected config: RequiredBaseClientConfig;
+    protected logger: Logger;
+    private interceptors;
+    constructor(config: BaseClientConfig);
+    /**
+     * Make an HTTP request with timeout and error handling
+     */
+    protected request<T>(endpoint: string, options?: RequestInit, serviceURL?: string, requestOptions?: RequestOptions): Promise<T>;
+    /**
+     * Make an HTTP request with retry logic
+     */
+    protected requestWithRetry<T>(endpoint: string, options?: RequestInit, serviceURL?: string, retries?: number, requestOptions?: RequestOptions): Promise<T>;
+    /**
+     * Handle error responses from API
+     */
+    protected handleErrorResponse(status: number, data: Record<string, unknown>): never;
+    /**
+     * Build query string from parameters
+     */
+    protected buildQueryString(params: Record<string, unknown>): string;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<BaseClientConfig>): void;
+    /**
+     * Get current configuration (readonly)
+     */
+    getConfig(): Readonly<BaseClientConfig>;
+    /**
+     * Health check endpoint
+     */
+    healthCheck(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+}
+
+export { BaseClient as B };

package/dist/client-VKJg2GGT.d.mts

@@ -0,0 +1,253 @@
+import { B as BaseClient } from './client-B7YzKVEm.mjs';
+import { R as RequestOptions, P as PaginationParams } from './types-DBGM-bFB.mjs';
+import { G as GeolocationClientConfig, V as VerifyIPRequest, L as LocationVerification, C as ComplianceCheckResponse, a as GeolocationConfigResponse, b as CipherTextReason, c as CipherTextCustomerData, d as ValidateCipherTextResponse, e as CreateLocationRequestRequest, f as LocationRequestResult, g as LocationRequest, h as LocationRequestFilters, i as LocationRequestListResponse, R as ResendLocationRequestRequest, j as LocationShareInfo, k as LocationCaptureRequest, l as LocationCaptureResponse } from './types-DGbuL8c0.mjs';
+
+/**
+ * GeolocationClient - TypeScript SDK for CGS Geolocation & Compliance Service
+ *
+ * Provides type-safe methods to interact with the geolocation service API.
+ * Extends BaseClient for consistent retry logic, timeout handling, and error management.
+ */
+
+/**
+ * GeolocationClient extends BaseClient for:
+ * - Consistent retry logic with exponential backoff
+ * - Unified error handling (CGSError, NetworkError, TimeoutError, etc.)
+ * - Automatic timeout management
+ * - Debug logging
+ *
+ * All geolocation verification calls use requestWithRetry() to handle
+ * transient failures gracefully.
+ */
+declare class GeolocationClient extends BaseClient {
+    constructor(config: GeolocationClientConfig);
+    /**
+     * Verify an IP address and check compliance
+     *
+     * Uses requestWithRetry() for automatic retry on transient failures.
+     *
+     * @param request - Verification request with IP, user ID, event type, and optional device fingerprint
+     * @returns Location verification result with risk assessment
+     *
+     * @example
+     * ```typescript
+     * const result = await client.verifyIP({
+     *   ip_address: "8.8.8.8",
+     *   user_id: "user_123",
+     *   event_type: "login",
+     *   device_fingerprint: {
+     *     device_id: "device_abc",
+     *     user_agent: navigator.userAgent,
+     *     platform: "web"
+     *   }
+     * });
+     *
+     * if (result.is_blocked) {
+     *   console.log("Access blocked:", result.risk_reasons);
+     * }
+     * ```
+     */
+    verifyIP(request: VerifyIPRequest, requestOptions?: RequestOptions): Promise<LocationVerification>;
+    /**
+     * Check compliance for a specific country
+     *
+     * @param countryISO - ISO 3166-1 alpha-2 country code (e.g., "US", "GB")
+     * @returns Jurisdiction configuration and compliance status
+     *
+     * @example
+     * ```typescript
+     * const compliance = await client.checkCompliance("KP"); // North Korea
+     * if (!compliance.is_compliant) {
+     *   console.log("Country is not allowed:", compliance.jurisdiction?.status);
+     * }
+     * ```
+     */
+    checkCompliance(countryISO: string, requestOptions?: RequestOptions): Promise<ComplianceCheckResponse>;
+    /**
+     * Get the tenant's GPS requirement configuration
+     *
+     * Returns which event types require GPS location to be collected.
+     * Use this to auto-enable GPS collection in generateCipherText when required.
+     *
+     * @returns GPS requirement config per event type
+     *
+     * @example
+     * ```typescript
+     * const config = await client.getGPSConfig();
+     * if (config.require_gps.login) {
+     *   // GPS is required for login — auto-enable location
+     * }
+     * ```
+     */
+    getGPSConfig(requestOptions?: RequestOptions): Promise<GeolocationConfigResponse>;
+    /**
+     * Validate a cipherText generated by the frontend SDK
+     *
+     * The cipherText contains encrypted device fingerprint and optional location data.
+     * This method decrypts and validates the data, returning device info, location,
+     * and risk assessment.
+     *
+     * @param cipherText - The encrypted cipherText string from generateCipherText()
+     * @param userId - User ID associated with this verification
+     * @param eventType - Reason for verification (login, registration, etc.)
+     * @param expectedIP - Optional expected IP address for additional validation
+     * @param customerData - Optional customer data for risk profile creation (used when user is blocked)
+     * @returns Validation result with device info, location, and risk assessment
+     *
+     * @example
+     * ```typescript
+     * // Validate cipherText during registration with customer data
+     * const result = await client.validateCipherText(
+     *   cipherText,
+     *   "user_123",
+     *   "registration",
+     *   clientIP,
+     *   {
+     *     full_name: "John Doe",
+     *     email: "john@example.com",
+     *     country: "US",
+     *     state: "CA"
+     *   }
+     * );
+     *
+     * if (!result.valid) {
+     *   console.log("CipherText validation failed:", result.errors);
+     *   return;
+     * }
+     *
+     * if (result.risk.is_blocked) {
+     *   console.log("Access blocked:", result.risk.block_reasons);
+     *   // A risk profile with full customer data has been created for the alert
+     * }
+     * ```
+     */
+    validateCipherText(cipherText: string, userId: string, eventType: CipherTextReason, expectedIP?: string, customerData?: CipherTextCustomerData, requestOptions?: RequestOptions): Promise<ValidateCipherTextResponse>;
+    /**
+     * Validate cipherText and verify IP in a single call
+     *
+     * Combines cipherText validation with IP verification for complete
+     * location and device verification in one request.
+     *
+     * @param cipherText - The encrypted cipherText string
+     * @param ipAddress - Client IP address
+     * @param userId - User ID
+     * @param eventType - Event type (login, registration, etc.)
+     * @returns Combined validation and verification result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.validateAndVerify(
+     *   cipherText,
+     *   clientIP,
+     *   "user_123",
+     *   "registration"
+     * );
+     *
+     * if (!result.ciphertext_valid) {
+     *   throw new Error("Device verification failed");
+     * }
+     *
+     * if (result.location.is_blocked) {
+     *   throw new Error("Location not allowed");
+     * }
+     * ```
+     */
+    validateAndVerify(cipherText: string, ipAddress: string, userId: string, eventType: CipherTextReason, requestOptions?: RequestOptions): Promise<{
+        ciphertext_valid: boolean;
+        ciphertext_result: ValidateCipherTextResponse;
+        location: LocationVerification;
+    }>;
+    /**
+     * Create a location request to get customer's live location
+     *
+     * @param request - Location request details
+     * @returns Location request result with share link
+     *
+     * @example
+     * ```typescript
+     * const result = await client.createLocationRequest({
+     *   user_id: "customer_123",
+     *   channel: "sms",
+     *   phone: "+1234567890",
+     *   reason: "Verification for high-value transaction"
+     * });
+     *
+     * console.log(`Share link sent: ${result.share_link}`);
+     * console.log(`Expires at: ${result.token_expiry}`);
+     * ```
+     */
+    createLocationRequest(request: CreateLocationRequestRequest, requestOptions?: RequestOptions): Promise<LocationRequestResult>;
+    /**
+     * Get a location request by ID
+     *
+     * @param requestId - Location request ID
+     * @returns Location request details
+     */
+    getLocationRequest(requestId: string, requestOptions?: RequestOptions): Promise<LocationRequest>;
+    /**
+     * List location requests with filters and pagination
+     *
+     * @param filters - Optional filters
+     * @param pagination - Optional pagination
+     * @returns Paginated list of location requests
+     *
+     * @example
+     * ```typescript
+     * const requests = await client.listLocationRequests(
+     *   { status: "completed", user_id: "customer_123" },
+     *   { page: 1, limit: 20 }
+     * );
+     * ```
+     */
+    listLocationRequests(filters?: LocationRequestFilters, pagination?: PaginationParams, requestOptions?: RequestOptions): Promise<LocationRequestListResponse>;
+    /**
+     * Cancel a pending location request
+     *
+     * @param requestId - Location request ID
+     */
+    cancelLocationRequest(requestId: string, requestOptions?: RequestOptions): Promise<void>;
+    /**
+     * Resend notification for a location request
+     *
+     * @param requestId - Location request ID
+     * @param contact - Email or phone to send to
+     */
+    resendLocationRequest(requestId: string, contact: ResendLocationRequestRequest, requestOptions?: RequestOptions): Promise<void>;
+    /**
+     * Get location share info (customer-facing)
+     * This is called from the customer's device to get request details
+     *
+     * @param token - Secure token from share link
+     * @returns Location share info
+     */
+    getLocationShareInfo(token: string, requestOptions?: RequestOptions): Promise<LocationShareInfo>;
+    /**
+     * Submit location capture (customer-facing)
+     * This is called from the customer's device to submit their location
+     *
+     * @param token - Secure token from share link
+     * @param capture - Location capture data (GPS or WiFi)
+     * @returns Capture response
+     *
+     * @example
+     * ```typescript
+     * // Using GPS (preferred)
+     * const result = await client.captureLocation(token, {
+     *   latitude: 37.7749,
+     *   longitude: -122.4194,
+     *   accuracy: 10
+     * });
+     *
+     * // Using WiFi positioning (fallback)
+     * const result = await client.captureLocation(token, {
+     *   wifi_networks: [
+     *     { macAddress: "00:11:22:33:44:55", signalStrength: -50 },
+     *     { macAddress: "AA:BB:CC:DD:EE:FF", signalStrength: -70 }
+     *   ]
+     * });
+     * ```
+     */
+    captureLocation(token: string, capture: LocationCaptureRequest, requestOptions?: RequestOptions): Promise<LocationCaptureResponse>;
+}
+
+export { GeolocationClient as G };