vesant-sdk 1.0.4

package/README.md

@@ -0,0 +1,247 @@
+# Vesant Compliance SDK
+
+> TypeScript SDK for Vesant Compliance Platform - Geolocation Verification, Risk Profiling, and Compliance Orchestration
+
+## Features
+
+- **Geolocation Compliance** - IP verification, VPN/proxy 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 vesant-compliance-sdk
+# or
+yarn add vesant-compliance-sdk
+# or
+pnpm add vesant-compliance-sdk
+```
+
+## Quick Start
+
+### Initialize the SDK
+
+```typescript
+import { ComplianceClient } from 'vesant-compliance-sdk';
+
+const sdk = new ComplianceClient({
+  baseURL: process.env.VESANT_API_URL,
+  tenantId: process.env.VESANT_TENANT_ID,
+  apiKey: process.env.VESANT_API_KEY
+});
+```
+
+### Registration Verification
+
+```typescript
+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) {
+  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
+  }
+} else {
+  console.log('Registration blocked:', result.blockReasons);
+}
+```
+
+### Login Verification
+
+```typescript
+const result = await sdk.verifyAtLogin({
+  customerId: 'CUST-12345',
+  ipAddress: req.ip,
+  deviceFingerprint: getDeviceFingerprint()
+});
+
+if (result.allowed) {
+  if (result.requiresStepUp) {
+    // Trigger MFA/2FA
+  } else {
+    // Allow login
+  }
+} else {
+  console.log('Login blocked:', result.blockReasons);
+}
+```
+
+### Transaction Verification
+
+```typescript
+const result = await sdk.verifyAtTransaction({
+  customerId: 'CUST-12345',
+  ipAddress: req.ip,
+  amount: 5000,
+  currency: 'USD',
+  transactionType: 'withdrawal'
+});
+
+if (result.allowed) {
+  // Process transaction
+} else if (result.requiresApproval) {
+  // Queue for manual review
+} else {
+  console.log('Transaction blocked:', result.blockReasons);
+}
+```
+
+## Module-Specific Imports
+
+Import only what you need to reduce bundle size:
+
+### Geolocation Only
+
+```typescript
+import { GeolocationClient } from 'vesant-compliance-sdk/geolocation';
+
+const geoClient = new GeolocationClient({
+  baseURL: process.env.VESANT_API_URL,
+  tenantId: process.env.VESANT_TENANT_ID,
+  apiKey: process.env.VESANT_API_KEY
+});
+
+const verification = await geoClient.verifyIP({
+  ip_address: '8.8.8.8',
+  user_id: 'user-123',
+  event_type: 'login'
+});
+
+console.log('Country:', verification.location.country_iso);
+console.log('Is VPN:', verification.location.is_vpn);
+console.log('Risk level:', verification.risk_level);
+```
+
+### Risk Profile Only
+
+```typescript
+import { RiskProfileClient } from 'vesant-compliance-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
+});
+
+const profile = await riskClient.getProfile('CUST-12345');
+console.log('Risk score:', profile.risk_score);
+console.log('Risk category:', profile.risk_category);
+```
+
+## React Hooks
+
+```typescript
+import { useRegistration } from 'vesant-compliance-sdk/react';
+
+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()
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Form fields */}
+      <button disabled={loading}>
+        {loading ? 'Verifying...' : 'Register'}
+      </button>
+      {error && <ErrorMessage>{error.message}</ErrorMessage>}
+    </form>
+  );
+}
+```
+
+## 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)
+}
+```
+
+## API Methods
+
+### ComplianceClient
+
+| Method | Description |
+|--------|-------------|
+| `verifyAtRegistration(request)` | Verify new user registration |
+| `verifyAtLogin(request)` | Verify user login |
+| `verifyAtTransaction(request)` | Verify financial transaction |
+| `requestCustomerLocation(input)` | Request live GPS location from customer |
+| `getLocationRequest(requestId)` | Get location request status |
+
+### GeolocationClient
+
+| Method | Description |
+|--------|-------------|
+| `verifyIP(request)` | Verify IP address and check compliance |
+| `validateCipherText(cipherText, userId, eventType)` | Validate device fingerprint |
+| `listAlerts(filters)` | List compliance alerts |
+| `listJurisdictions()` | Get jurisdiction configurations |
+
+### RiskProfileClient
+
+| Method | Description |
+|--------|-------------|
+| `createProfile(request)` | Create customer risk profile |
+| `getProfile(customerId)` | Get profile by customer ID |
+| `updateProfile(profileId, updates)` | Update customer profile |
+| `getDashboardMetrics()` | Get risk dashboard metrics |
+
+## 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)
+- [Registration Flow](./docs/guides/registration.md)
+- [Login Flow](./docs/guides/login.md)
+- [Transaction Verification](./docs/guides/transactions.md)
+- [React Hooks](./docs/react-hooks/overview.md)
+- [Error Handling](./docs/advanced/error-handling.md)
+
+## License
+
+MIT
+
+## Support
+
+For support, contact your Vesant account representative or visit the [support portal](https://support.vesant.ai).