cdp-lite-sdk 0.1.1 → 0.1.3

package/README.md

@@ -11,6 +11,7 @@
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+- [Security Features](#security-features)
 - [Core Methods](#core-methods)
 - [Advanced Usage](#advanced-usage)
 - [React Integration](#react-integration)
@@ -21,10 +22,12 @@
 
 ---
 
-## ✨ Features
+<h2 id="features">✨ Features</h2>
 
 - ✅ **Event Tracking** - Track custom events with properties
 - ✅ **User Identification** - Identify and track users
+- 🔒 **Data Encryption** - AES-256-CBC encryption for sensitive user data
+- 🔐 **Request Signing** - HMAC-SHA256 signatures for API security
 - ✅ **Batch Processing** - Auto-batch events for optimal performance
 - ✅ **Device Detection** - Auto-detect device information
 - ✅ **Anonymous Tracking** - Track users before identification
@@ -37,7 +40,7 @@
 
 ---
 
-## 📦 Installation
+<h2 id="#installation">📦 Installation</h2>
 
 ### NPM
 
@@ -59,29 +62,31 @@ yarn add cdp-lite-sdk
 
 ---
 
-## 🚀 Quick Start
+<h2 id="#quick-start">🚀 Quick Start</h2>
 
 ### ES6 Import (Recommended)
 
 ```javascript
 import CdpLiteSdk from 'cdp-lite-sdk';
 
-// Initialize SDK
+// Initialize SDK with security
 const cdp = new CdpLiteSdk({
   apiKey: 'your-api-key',
+  secretKey: 'your-secret-key',  // Required for encryption & signatures
   source: 'YourApp',
   serviceName: 'YourService',
   isTest: true,
   debug: true
 });
 
-// Identify user
+// Identify user (sensitive data auto-encrypted)
 cdp.identify('user_123', {
-  name: 'John Doe',
-  email: 'john@example.com'
+  full_name: 'John Doe',
+  email: 'john@example.com',
+  phone: '0901234567'
 });
 
-// Track event
+// Track event (auto-signed with HMAC)
 cdp.track('button_clicked', {
   button_name: 'Sign Up',
   page: 'Landing'
@@ -115,7 +120,7 @@ const cdp = new CdpLiteSdk({
 
 ---
 
-## ⚙️ Configuration
+<h2 id="#configuration">⚙️ Configuration</h2>
 
 ### Configuration Options
 
@@ -124,6 +129,10 @@ const cdp = new CdpLiteSdk({
   // Required
   apiKey: 'string',              // Your API key
   
+  // Security (Recommended)
+  secretKey: 'string',           // Secret key for encryption & signatures
+  enableEncryption: boolean,     // Enable traits encryption (default: true)
+  
   // Optional
   source: 'string',              // Source name (default: 'Web')
   serviceName: 'string',         // Service name (default: 'DefaultService')
@@ -143,9 +152,10 @@ const cdp = new CdpLiteSdk({
 ```javascript
 const cdp = new CdpLiteSdk({
   apiKey: 'dev-api-key',
+  secretKey: 'dev-secret-key',
   source: 'MyApp',
   serviceName: 'MyService',
-  baseUrl: 'https://vconnect-dev.vietcredit.com.vn',
+  baseUrl: 'https://stg-ingestlog.vietcredit.com.vn',
   isTest: true,
   debug: true,
   batchSize: 5,
@@ -158,6 +168,7 @@ const cdp = new CdpLiteSdk({
 ```javascript
 const cdp = new CdpLiteSdk({
   apiKey: process.env.CDP_API_KEY,
+  secretKey: process.env.CDP_SECRET_KEY,
   source: 'MyApp',
   serviceName: 'MyService',
   baseUrl: 'https://vconnect.vietcredit.com.vn',
@@ -170,7 +181,48 @@ const cdp = new CdpLiteSdk({
 
 ---
 
-## 📚 Core Methods
+<h2 id="#security-features">🔒 Security Features</h2>
+
+### Automatic Data Encryption
+
+SDK automatically encrypts sensitive user data using **AES-256-CBC** before sending:
+
+```javascript
+// Sensitive data is automatically encrypted
+cdp.identify('user_123', {
+  email: 'user@example.com',      // Encrypted
+  phone: '0901234567',             // Encrypted
+  idcard: '001234567890',          // Encrypted
+  
+  // Other fields are not encrypted
+  city: 'Hanoi',
+  age: 30
+});
+```
+
+### Request Signing
+
+All API requests are signed with **HMAC-SHA256** for authentication:
+
+```
+X-Signatures = Base64(HMAC-SHA256(X-Source + "|" + X-Timestamp + "|" + Payload))
+```
+
+### Setup Security
+
+```javascript
+const cdp = new CdpLiteSdk({
+  apiKey: process.env.CDP_API_KEY,
+  secretKey: process.env.CDP_SECRET_KEY,  // Required for security
+  enableEncryption: true  // Default: true
+});
+```
+
+**📖 See [SECURITY.md](SECURITY.md) for complete security documentation.**
+
+---
+
+<h2 id="#core-methods">📚 Core Methods</h2>
 
 ### 1. Track Events
 
@@ -231,15 +283,32 @@ cdp.identify(userId, traits);
 
 ```javascript
 cdp.identify('user_123', {
-  name: 'John Doe',
-  email: 'john@example.com',
+  // Sensitive fields (auto-encrypted)
+  full_name: 'Nguyen Van A',
+  first_name: 'A',
+  last_name: 'Nguyen Van',
+  email: 'user@example.com',
   phone: '+84901234567',
+  idcard: '001234567890',
+  dob: '1990-01-01',
+  gender: 'male',
+  address: '123 ABC Street, Hanoi',
+  religion: 'Buddhism',
+  
+  // Non-sensitive fields (not encrypted)
   age: 30,
   city: 'Hanoi',
   plan: 'premium'
 });
 ```
 
+**Sensitive Fields (Auto-Encrypted):**
+- `full_name`, `first_name`, `last_name`
+- `idcard`, `old_idcard`
+- `phone`, `email`
+- `gender`, `dob`
+- `address`, `religion`
+
 ### 3. Page Views
 
 Track page views (for web applications).
@@ -368,7 +437,7 @@ cdp.destroy();
 
 ---
 
-## 🔥 Advanced Usage
+<h2 id="#advanced-usage">🔥 Advanced Usage</h2>
 
 ### Batch Processing
 
@@ -427,7 +496,7 @@ cdp.track('checkout', {
 
 ---
 
-## ⚛️ React Integration
+<h2 id="react-integration">⚛️ React Integration</h2>
 
 ### Setup Analytics Context
 
@@ -525,7 +594,7 @@ function App() {
 
 ---
 
-## 🎯 TypeScript Support
+<h2 id="#typescript-support">🎯 TypeScript Support</h2>
 
 Full TypeScript support with type definitions.
 
@@ -559,12 +628,21 @@ cdp.track('purchase', eventProps);
 
 ---
 
-## 📖 API Reference
+<h2 id="#api-reference">📖 API Reference</h2>
 
 ### Constructor
 
 ```typescript
-new CdpLiteSdk(config: CdpConfig)
+const config: CdpLiteSdk = {
+  apiKey: 'your-api-key',
+  secretKey: 'your-secret-key',  // Required for security features
+  source: 'YourApp',
+  serviceName: 'YourService',
+  enableEncryption: true,  // Enable encryption (default: true)
+  debug: true
+}
+
+const sdk = new CdpLiteSdk(config)
 ```
 
 ### Methods
@@ -583,7 +661,7 @@ new CdpLiteSdk(config: CdpConfig)
 
 ---
 
-## 💡 Examples
+<h2 id="#examples">💡 Examples</h2>
 
 ### E-commerce Tracking
 
@@ -696,7 +774,7 @@ cdp.track('form_submitted', {
 
 ---
 
-## 🐛 Troubleshooting
+<h2 id="#troubleshooting">🐛 Troubleshooting</h2>
 
 ### Events Not Sending
 
@@ -799,11 +877,30 @@ cdp.track('CHECKOUT');
 
 ## 🔒 Privacy & Security
 
-- SDK automatically generates anonymous IDs
-- User data is only sent after explicit `identify()` call
-- All data transmitted over HTTPS
-- API keys should be kept secure
-- Never commit API keys to version control
+- 🔐 **AES-256-CBC Encryption** for sensitive user data
+- 🔑 **HMAC-SHA256 Signatures** for request authentication
+- 🆔 **Anonymous IDs** generated automatically
+- 📊 **Selective Encryption** - only sensitive fields are encrypted
+- 🔒 **HTTPS Only** - all data transmitted over secure connections
+- 🔑 **Secret Key Protection** - never expose secret keys
+- 🚫 **No Plain Text** - sensitive data never sent unencrypted
+
+**Security Best Practices:**
+```javascript
+// ✅ Use environment variables
+const cdp = new CdpLiteSdk({
+  apiKey: process.env.CDP_API_KEY,
+  secretKey: process.env.CDP_SECRET_KEY
+});
+
+// ❌ Never hardcode keys
+const cdp = new CdpLiteSdk({
+  apiKey: 'abc123',  // DON'T DO THIS
+  secretKey: 'secret123'
+});
+```
+
+**📖 Full Security Guide:** [SECURITY.md](SECURITY.md)
 
 ---
 
@@ -814,9 +911,7 @@ MIT License - see LICENSE file for details
 ---
 
 ## 🤝 Support
-
-- **Email:** vinv@vega.com.vn
-
+- 📧 Email: vinv@vega.com.vn
 ---
 
 ## 🎉 Quick Reference