{"_id":"@cartai2025/sdk","_rev":"2-0efd6d308a77c00dfab1d6cbbd14eb2b","name":"@cartai2025/sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@cartai2025/sdk","version":"1.0.0","keywords":["cartai","device-fingerprinting","browser-tracking","analytics","fraud-prevention","socket.io"],"author":{"url":"https://cartai.com","name":"CartAI, Inc"},"license":"MIT","_id":"@cartai2025/sdk@1.0.0","maintainers":[{"name":"cartai","email":"cartai2025@gmail.com"}],"dist":{"shasum":"c7e080355fbb4de351862fa8558912cf66a63617","tarball":"https://registry.npmjs.org/@cartai2025/sdk/-/sdk-1.0.0.tgz","fileCount":9,"integrity":"sha512-Ec6nzd3T1xUrC3lSaRACMMhGLnOxt8Ent9CMr0VUOp2tjQgZXQNyfjY07lFnAVydA6bxusGga7k036hNuWmt8w==","signatures":[{"sig":"MEYCIQDxYwmODQTkW9BjAUtuQ9AbIJUCgyiDPz0vyL6Ra7D9ggIhAOmhWmGdr5sP/Ifnx0ifxKxWkgxJPycv36ZgboKboAEP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":522969},"main":"dist/cartai-sdk.cjs.js","types":"dist/cartai-sdk.d.ts","module":"dist/cartai-sdk.esm.js","gitHead":"8facb5d174dd72861f35121d42ee1f6b3b8e5080","scripts":{"dev":"rollup -c rollup.config.js --watch","lint":"eslint --ext .js,.ts --ignore-path .gitignore --max-warnings 0 .","test":"echo 'CartAI SDK tests not implemented yet'","build":"rimraf dist && rollup -c rollup.config.js","start":"echo 'CartAI SDK start not implemented yet'","lint:fix":"yarn lint --fix","build:watch":"yarn build --watch"},"_npmUser":{"name":"cartai","email":"cartai2025@gmail.com"},"_npmVersion":"10.8.2","description":"Comprehensive CartAI SDK with device fingerprinting, browser event tracking, and Socket.IO integration.","directories":{},"sideEffects":false,"_nodeVersion":"20.19.5","dependencies":{"tslib":"^2.8.1","socket.io-client":"^4.7.5"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.50.0","rimraf":"^5.0.5","rollup":"^4.0.2","ts-node":"^10.9.1","prettier":"^3.0.3","typescript":"^5.2.2","@types/node":"^20.8.0","rollup-plugin-dts":"^6.1.0","@rollup/plugin-json":"^6.0.1","@rollup/plugin-terser":"^0.4.4","rollup-plugin-license":"^3.2.0","@cartai2025/device-sdk":"file:../cartai-device-sdk","eslint-config-prettier":"^9.0.0","eslint-plugin-prettier":"^5.0.0","@rollup/plugin-typescript":"^11.1.5","@typescript-eslint/parser":"^6.7.4","@rollup/plugin-node-resolve":"^15.2.3","@typescript-eslint/eslint-plugin":"^6.7.4"},"peerDependencies":{"@cartai2025/device-sdk":"^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1759521797401_0.8891801308128489","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@cartai2025/sdk","version":"1.0.2","description":"Comprehensive CartAI SDK with device fingerprinting, browser event tracking, and Socket.IO integration","keywords":["cartai","device-fingerprinting","browser-tracking","analytics","fraud-prevention","socket.io"],"author":{"name":"CartAI, Inc","url":"https://cartai.com"},"license":"MIT","main":"dist/cartai-sdk.cjs.js","module":"dist/cartai-sdk.esm.js","types":"dist/cartai-sdk.d.ts","sideEffects":false,"scripts":{"build":"rimraf dist && rollup -c rollup.config.js","build:watch":"yarn build --watch","dev":"rollup -c rollup.config.js --watch","test":"echo 'CartAI SDK tests not implemented yet'","lint":"eslint --ext .js,.ts --ignore-path .gitignore --max-warnings 0 .","lint:fix":"yarn lint --fix","start":"echo 'CartAI SDK start not implemented yet'"},"dependencies":{"socket.io-client":"^4.7.5","tslib":"^2.8.1"},"devDependencies":{"@cartai2025/device-sdk":"file:../cartai-device-sdk","@rollup/plugin-json":"^6.0.1","@rollup/plugin-node-resolve":"^15.2.3","@rollup/plugin-terser":"^0.4.4","@rollup/plugin-typescript":"^11.1.5","@types/node":"^20.8.0","@typescript-eslint/eslint-plugin":"^6.7.4","@typescript-eslint/parser":"^6.7.4","eslint":"^8.50.0","eslint-config-prettier":"^9.0.0","eslint-plugin-prettier":"^5.0.0","prettier":"^3.0.3","rimraf":"^5.0.5","rollup":"^4.0.2","rollup-plugin-dts":"^6.1.0","rollup-plugin-license":"^3.2.0","ts-node":"^10.9.1","typescript":"^5.2.2"},"peerDependencies":{"@cartai2025/device-sdk":"^1.0.0"},"_id":"@cartai2025/sdk@1.0.2","gitHead":"7479c28d4e86538ccac50fc3f17d6cc011d31fd4","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-485rFdtgEtUyqoQvH/U9hhOSRiIUv3zu8csb8yYudSbKYzdq6B5cdccJ1KztlP1LrizNfLJPjMhxEaXCx6M8Pw==","shasum":"97f94afc294808b25153507622cbd92afa96d7e2","tarball":"https://registry.npmjs.org/@cartai2025/sdk/-/sdk-1.0.2.tgz","fileCount":9,"unpackedSize":522988,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDFhYfeVJQhfJNAB163CtlXMSml+Rn7ZtuoznY4dyGtBgIgZpD6qRmXdQLo7rMNK4ST9uSULBeei3Dp6H4JuhnX+Kc="}]},"_npmUser":{"name":"cartai","email":"cartai2025@gmail.com"},"directories":{},"maintainers":[{"name":"cartai","email":"cartai2025@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.2_1759585560127_0.6990912280559145"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-03T20:03:17.296Z","modified":"2025-10-04T13:46:00.675Z","1.0.0":"2025-10-03T20:03:17.631Z","1.0.2":"2025-10-04T13:46:00.392Z"},"author":{"name":"CartAI, Inc","url":"https://cartai.com"},"license":"MIT","keywords":["cartai","device-fingerprinting","browser-tracking","analytics","fraud-prevention","socket.io"],"description":"Comprehensive CartAI SDK with device fingerprinting, browser event tracking, and Socket.IO integration","maintainers":[{"name":"cartai","email":"cartai2025@gmail.com"}],"readme":"# CartAI SDK\n\nComprehensive JavaScript SDK for device fingerprinting, browser event tracking, and real-time analytics with Socket.IO integration.\n\n## 🚀 Features\n\n### Core Functionality\n- **Device Fingerprinting**: Advanced browser identification with fallback support\n- **Socket.IO Integration**: Real-time communication with CartAI backend\n- **Browser Event Tracking**: Comprehensive user behavior analytics\n- **Auto-Detection**: Email and phone number capture from form inputs\n- **Session Management**: Cross-session user tracking and analytics\n- **TypeScript Support**: Full type definitions included\n\n### Browser Events Tracking\n- **URL Changes**: Page navigation and time spent tracking\n- **Form Inputs**: Email/phone capture with automatic visitor linking\n- **Click Events**: User interaction monitoring with element details\n- **Scroll Events**: Engagement tracking and scroll behavior analysis\n- **Payment Events**: Transaction status and payment method tracking\n- **Sales Events**: Product views, cart actions, and purchase funnel analysis\n- **Custom Events**: Track any custom user interactions\n\n### Advanced Features\n- **Automatic Event Batching**: Efficient event sending with configurable batch sizes\n- **Fallback Fingerprinting**: Works even without CartAI Device SDK\n- **Real-time Analytics**: Live updates and behavior insights\n- **Cross-Device Tracking**: Enhanced visitor identification\n- **Debug Mode**: Comprehensive logging for development\n- **Multi-Format Builds**: IIFE, UMD, CJS, and ESM support\n\n## 📦 Installation\n\n### NPM/Yarn\n```bash\nnpm install @cartai2025/sdk socket.io-client\n# or\nyarn add @cartai2025/sdk socket.io-client\n```\n\n### CDN (Browser)\n```html\n<!-- Minified version -->\n<script src=\"https://d24lz8mxe7yhfu.cloudfront.net/cartai-sdk/cartai-sdk.min.js\"></script>\n\n<!-- Development version -->\n<script src=\"https://d24lz8mxe7yhfu.cloudfront.net/cartai-sdk/cartai-sdk.js\"></script>\n```\n\n## 🎯 Quick Start\n\n### Basic Setup\n\n```javascript\nimport { createCartAI } from '@cartai2025/sdk'\n\n// Initialize the SDK\nconst cartai = await createCartAI({\n  serverUrl: 'http://localhost:8000',\n  apiKey: 'cartai_sk_4f8b5e9a2c1d3f6e8b7a9c2e4f1b8d5a3e7c9f2b4e6a8c1d3f5e7b9a2c4e6f8b1',\n  debug: true,\n  enableEventTracking: true\n})\n\n// Send fingerprint data\nawait cartai.sendFingerprint()\n\n// Set user information\ncartai.setUserInfo({\n  email: 'user@example.com',\n  phone: '+1234567890'\n})\n\n// Track custom events\ncartai.trackEvent({\n  type: 'custom',\n  data: {\n    action: 'button_click',\n    element: 'cta-button'\n  }\n})\n```\n\n### Browser (IIFE)\n\n```html\n<!DOCTYPE html>\n<html>\n<head>\n  <script src=\"./dist/cartai-sdk.min.js\"></script>\n</head>\n<body>\n  <script>\n    // CartAI SDK is available as CartAISDK global\n    CartAISDK.createCartAI({\n      serverUrl: 'http://localhost:8000',\n      apiKey: 'your-api-key',\n      debug: true\n    }).then(async (cartai) => {\n      console.log('CartAI SDK initialized')\n      \n      // Send fingerprint\n      await cartai.sendFingerprint()\n      \n      // Track custom event\n      cartai.trackSales({\n        eventType: 'purchase',\n        productId: 'prod_123',\n        productName: 'Demo Product',\n        category: 'electronics',\n        value: 99.99\n      })\n    })\n  </script>\n</body>\n</html>\n```\n\n## 🔧 Configuration\n\n### CartAIConfig Options\n\n```typescript\ninterface CartAIConfig {\n  serverUrl: string              // Socket.IO server URL\n  apiKey: string                 // Authentication API key\n  loadOptions?: any              // Device SDK options\n  autoConnect?: boolean          // Auto-connect on init (default: true)\n  debug?: boolean                // Debug logging (default: false)\n  enableEventTracking?: boolean  // Auto event tracking (default: true)\n  customVisitorId?: string       // Custom visitor ID\n  eventBatchSize?: number        // Events per batch (default: 10)\n  eventSendInterval?: number     // Batch send interval ms (default: 10000)\n}\n```\n\n## 📊 Event Tracking\n\n### Automatic Event Tracking\n\nWhen `enableEventTracking` is true, the SDK automatically tracks:\n\n- **URL Changes**: Page navigation with time spent\n- **Clicks**: All click events with element details\n- **Scrolling**: Scroll behavior and engagement\n- **Form Inputs**: Input events with email/phone detection\n- **Page Visibility**: Tab switching and focus changes\n\n### Manual Event Tracking\n\n#### Form Input Events\n```javascript\ncartai.trackFormInput({\n  inputType: 'email',\n  fieldName: 'signup-email',\n  value: 'user@example.com',\n  isEmail: true,\n  fieldId: 'email-field'\n})\n```\n\n#### Payment Events\n```javascript\ncartai.trackPayment({\n  status: 'completed',\n  amount: 99.99,\n  currency: 'USD',\n  transactionId: 'txn_123456',\n  paymentMethod: 'credit_card',\n  salesAttributes: {\n    productId: 'prod_123',\n    orderId: 'order_789'\n  }\n})\n```\n\n#### Sales Events\n```javascript\ncartai.trackSales({\n  eventType: 'purchase',\n  productId: 'prod_123',\n  productName: 'Demo Product',\n  category: 'electronics',\n  value: 99.99,\n  salesAttributes: {\n    orderId: 'order_789',\n    couponCode: 'SAVE10'\n  }\n})\n```\n\n#### Custom Events\n```javascript\ncartai.trackEvent({\n  type: 'custom',\n  data: {\n    eventType: 'video_play',\n    videoId: 'demo_video',\n    duration: 120\n  }\n})\n```\n\n## 🔗 Socket.IO Integration\n\n### Server Events Sent\n- `fingerprint-data`: Device fingerprint data\n- `browser-events`: Batched browser events\n- `get-visitor-data`: Request visitor information\n- `get-stats`: Request analytics\n\n### Server Events Received\n- `fingerprint-stored`: Fingerprint confirmation\n- `browser-events-processed`: Events processed confirmation\n- `new-browser-activity`: Real-time activity updates\n- `error`: Error messages\n\n## 🎮 API Reference\n\n### Main Methods\n\n#### `createCartAI(config: CartAIConfig): Promise<CartAI>`\nFactory function to create and initialize the SDK.\n\n#### `initialize(): Promise<void>`\nInitialize the SDK (called automatically by `createCartAI`).\n\n#### `connect(): Promise<void>`\nConnect to Socket.IO server.\n\n#### `disconnect(): void`\nDisconnect from server and cleanup.\n\n#### `getFingerprint(): Promise<FingerprintResult>`\nGet device fingerprint data.\n\n#### `sendFingerprint(customData?: Record<string, any>): Promise<void>`\nSend fingerprint to server.\n\n### User & Location Data\n\n#### `setUserInfo(userInfo: UserInfo): void`\nSet user information for enhanced tracking.\n\n#### `setLocationData(locationData: LocationData): void`\nSet location data for user tracking.\n\n### Event Tracking Methods\n\n#### `trackEvent(event: BrowserEvent): void`\nTrack a custom browser event.\n\n#### `trackFormInput(data: FormInputData): void`\nTrack form input with auto email/phone detection.\n\n#### `trackPayment(data: PaymentData): void`\nTrack payment events.\n\n#### `trackSales(data: SalesData): void`\nTrack sales events.\n\n#### `sendBrowserEvents(events?: BrowserEvent[]): Promise<void>`\nSend browser events to server.\n\n### Utility Methods\n\n#### `getSessionInfo(): SessionInfo`\nGet current session information.\n\n#### `getQueuedEvents(): BrowserEvent[]`\nGet queued events.\n\n#### `clearQueuedEvents(): void`\nClear queued events.\n\n## 🏗️ Build & Development\n\n### Build Commands\n```bash\n# Install dependencies\nnpm install\n\n# Build all formats\nnpm run build\n\n# Build with watch mode\nnpm run dev\n\n# Lint code\nnpm run lint\n\n# Fix lint issues\nnpm run lint:fix\n```\n\n### Output Formats\n- `cartai-sdk.js` - IIFE for direct browser use\n- `cartai-sdk.min.js` - Minified IIFE\n- `cartai-sdk.umd.js` - UMD for universal usage\n- `cartai-sdk.umd.min.js` - Minified UMD\n- `cartai-sdk.cjs.js` - CommonJS for Node.js\n- `cartai-sdk.esm.js` - ES modules for bundlers\n- `cartai-sdk.d.ts` - TypeScript definitions\n\n## 🔒 Security & Privacy\n\n- **API Key Authentication**: Secure Socket.IO connections\n- **Password Field Exclusion**: Passwords are never tracked\n- **Data Truncation**: Form values limited to prevent large data\n- **Debug Mode Control**: Sensitive data logging controlled by debug flag\n\n## 🌐 Browser Compatibility\n\n- **Modern Browsers**: Chrome 60+, Firefox 60+, Safari 12+, Edge 79+\n- **Legacy Support**: Graceful degradation for older browsers\n- **Mobile Support**: iOS Safari 12+, Android Chrome 60+\n\n## 🤝 Integration with CartAI Device SDK\n\nThe SDK works seamlessly with `@cartai2025/device-sdk`:\n\n```html\n<!-- Include both SDKs -->\n<script src=\"./path-to/cartai.min.js\"></script>\n<script src=\"./path-to/cartai-sdk.min.js\"></script>\n\n<script>\n// CartAI Device SDK will be detected automatically\nCartAISDK.createCartAI({\n  serverUrl: 'http://localhost:8000',\n  apiKey: 'your-api-key'\n}).then(cartai => {\n  // Full fingerprinting + event tracking ready\n})\n</script>\n```\n\n## 📈 Example Use Cases\n\n### E-commerce Tracking\n```javascript\n// Track product views\ncartai.trackSales({\n  eventType: 'product_view',\n  productId: 'prod_123',\n  productName: 'Wireless Headphones',\n  category: 'electronics',\n  value: 199.99\n})\n\n// Track add to cart\ncartai.trackEvent({\n  type: 'custom',\n  data: {\n    action: 'add_to_cart',\n    productId: 'prod_123',\n    quantity: 1\n  }\n})\n\n// Track purchase\ncartai.trackPayment({\n  status: 'completed',\n  amount: 199.99,\n  currency: 'USD',\n  transactionId: 'txn_abc123',\n  paymentMethod: 'credit_card'\n})\n```\n\n### Lead Generation\n```javascript\n// Form completion tracking\ncartai.trackFormInput({\n  inputType: 'email',\n  fieldName: 'newsletter-signup',\n  value: 'user@example.com',\n  isEmail: true\n})\n\n// Custom lead scoring\ncartai.trackEvent({\n  type: 'custom',\n  data: {\n    action: 'whitepaper_download',\n    leadScore: 25,\n    category: 'high-intent'\n  }\n})\n```\n\n### Content Analytics\n```javascript\n// Article engagement\ncartai.trackEvent({\n  type: 'custom',\n  data: {\n    action: 'article_read',\n    articleId: 'art_456',\n    readingTime: 180,\n    completion: 75\n  }\n})\n\n// Video engagement\ncartai.trackEvent({\n  type: 'custom',\n  data: {\n    action: 'video_engagement',\n    videoId: 'vid_789',\n    watchTime: 120,\n    completion: 50\n  }\n})\n```\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n#### Connection Issues\n```javascript\n// Check connection status\nconst sessionInfo = cartai.getSessionInfo()\nconsole.log('Connected:', sessionInfo.isConnected)\n\n// Manual reconnection\nif (!sessionInfo.isConnected) {\n  await cartai.connect()\n}\n```\n\n#### Event Queue Management\n```javascript\n// Check queued events\nconst queuedEvents = cartai.getQueuedEvents()\nconsole.log(`${queuedEvents.length} events queued`)\n\n// Force send events\nawait cartai.sendBrowserEvents()\n\n// Clear queue if needed\ncartai.clearQueuedEvents()\n```\n\n#### Debug Mode\n```javascript\n// Enable debug logging\nconst cartai = await createCartAI({\n  serverUrl: 'http://localhost:8000',\n  apiKey: 'your-api-key',\n  debug: true // Enable detailed logging\n})\n```\n\n## 📚 TypeScript Support\n\nFull TypeScript definitions included:\n\n```typescript\nimport { CartAI, CartAIConfig, BrowserEvent, UserInfo } from '@cartai2025/sdk'\n\nconst config: CartAIConfig = {\n  serverUrl: 'http://localhost:8000',\n  apiKey: 'your-api-key',\n  debug: true\n}\n\nconst cartai: CartAI = await createCartAI(config)\n\nconst userInfo: UserInfo = {\n  email: 'user@example.com',\n  phone: '+1234567890',\n  userId: 'user_123'\n}\n\ncartai.setUserInfo(userInfo)\n```\n\n---\n\n## 🚀 Getting Started Checklist\n\n- [ ] Install the SDK via npm or include via CDN\n- [ ] Configure your CartAI backend server with Socket.IO\n- [ ] Initialize the SDK with your server URL and API key\n- [ ] Enable debug mode for development\n- [ ] Test fingerprint collection and event tracking\n- [ ] Set up user information and location data\n- [ ] Implement custom event tracking for your use case\n- [ ] Monitor real-time analytics in your backend\n- [ ] Deploy to production with proper API keys\n\n**Need help?** Check the troubleshooting section above or create an issue in the repository.\n\n---\n\n*CartAI SDK - Powering comprehensive user analytics with device fingerprinting and real-time event tracking*","readmeFilename":"README.md"}