@syntropysoft/syntropyfront 0.1.0-alpha.1 → 0.2.0

package/README.md

@@ -1,322 +1,402 @@
-<p align="center">
-  <img src="./assets/syntropysoft-logo.png" alt="SyntropyLog Logo" width="170"/>
-</p>
-
-<h1 align="center">SyntropyFront</h1>
-
-<p align="center">
-  <strong>From Chaos to Clarity</strong>
-  <br />
-  The Observability Framework for High-Performance Teams
-</p>
-<p align="center">
-  Advanced frontend tracing and error monitoring with reactive object tracking, worker architecture, and circular reference handling
-  <br />
-</p>
-
-## 🚀 Features
-
-- **🔄 Reactive Object Tracking** - Real-time object state tracking using JavaScript Proxies
-- **⚡ Worker Architecture** - Non-blocking data collection and processing
-- **🛡️ Circular Reference Handling** - Robust serialization for complex objects
-- **🎯 Configuration Presets** - Pre-configured setups for different use cases
-- **📦 Lazy Loading** - Dynamic module loading for optimal bundle size
-- **🔗 Framework Agnostic** - Works with any JavaScript framework
-- **📊 Breadcrumb System** - Comprehensive user action tracking
-- **🔄 Automatic Retry** - Exponential backoff with persistent buffer
-- **🔒 Privacy First** - Granular context collection with opt-in sensitive data
+# SyntropyFront
 
-## 📦 Installation
+🚀 **Observability library with automatic capture - Just 1 line of code!**
 
-```bash
-npm install syntropyfront
-```
+SyntropyFront automatically captures user interactions, errors, HTTP calls, and console logs, providing comprehensive observability for your web applications with minimal setup.
 
-## 🎯 Quick Start
+## ✨ Features
 
-```javascript
-import { SyntropyFront } from 'syntropyfront';
+- 🎯 **Automatic click capture** - Tracks all user interactions
+- 🚨 **Error detection** - Catches uncaught exceptions and promise rejections
+- 🌐 **HTTP monitoring** - Intercepts fetch calls automatically
+- 📝 **Console logging** - Records console.log, console.error, console.warn
+- 💾 **Smart storage** - Keeps the last N events (configurable)
+- 📤 **Flexible posting** - Posts errors to your endpoint or logs to console
+- ⚡ **Zero configuration** - Works out of the box with just an import
 
-// Initialize with balanced preset
-await SyntropyFront.init({
-  preset: 'balanced',
-  agent: {
-    endpoint: 'https://your-api.com/errors'
-  }
-});
+## 🚀 Quick Start
 
-// Add reactive object tracking
-const userProfile = SyntropyFront.addProxyObject('userProfile', {
-  name: 'John Doe',
-  preferences: { theme: 'dark' }
-});
+### Basic Usage (1 line of code!)
 
-// Track user actions automatically
-// Error handling is automatic
+```javascript
+import syntropyFront from 'syntropyfront';
+// That's it! Auto-initializes and captures everything automatically
 ```
 
-## ⚙️ Configuration Presets
+### With Custom Configuration
 
-### Safe Preset
 ```javascript
-await SyntropyFront.init({
-  preset: 'safe',
-  agent: { endpoint: 'https://api.com/errors' }
+import syntropyFront from 'syntropyfront';
+
+// Option 1: Console only (default)
+syntropyFront.configure({
+  maxEvents: 50
 });
-```
-- **Use case**: Production environments with privacy concerns
-- **Features**: Errors only, minimal context, no tracking
-- **Bundle size**: ~25KB
 
-### Balanced Preset (Default)
-```javascript
-await SyntropyFront.init({
-  preset: 'balanced',
-  agent: { endpoint: 'https://api.com/errors' }
+// Option 2: With endpoint (automatic fetch)
+syntropyFront.configure({
+  maxEvents: 50,
+  fetch: {
+    url: 'https://your-api.com/errors',
+    options: {
+      headers: {
+        'Authorization': 'Bearer your-token',
+        'Content-Type': 'application/json'
+      },
+      mode: 'cors'
+    }
+  }
 });
-```
-- **Use case**: General production use
-- **Features**: Periodic sending, curated context, moderate tracking
-- **Bundle size**: ~60KB
 
-### Debug Preset
-```javascript
-await SyntropyFront.init({
-  preset: 'debug',
-  agent: { endpoint: 'https://api.com/errors' }
+// Option 3: With custom error handler (maximum flexibility)
+syntropyFront.configure({
+  maxEvents: 50,
+  onError: (errorPayload) => {
+    // You can do anything with the error:
+    // - Send to your API
+    // - Save to localStorage
+    // - Send to a repository
+    // - Upload to cloud
+    // - Whatever you want!
+    console.log('Error captured:', errorPayload);
+    
+    // Example: send to multiple places
+    fetch('https://api1.com/errors', {
+      method: 'POST',
+      body: JSON.stringify(errorPayload)
+    });
+    
+    // Also save locally
+    localStorage.setItem('lastError', JSON.stringify(errorPayload));
+  }
 });
 ```
-- **Use case**: Development and debugging
-- **Features**: Frequent sending, full context, complete tracking
-- **Bundle size**: ~60KB
 
-### Performance Preset
-```javascript
-await SyntropyFront.init({
-  preset: 'performance',
-  agent: { endpoint: 'https://api.com/errors' }
-});
+## 📦 Installation
+
+```bash
+npm install syntropyfront
+## 🎯 How It Works
+
+SyntropyFront automatically:
+
+1. **Captures clicks** - Records element info, coordinates, and timestamps
+2. **Detects errors** - Intercepts `window.onerror` and `window.onunhandledrejection`
+3. **Monitors HTTP** - Wraps `window.fetch` to track requests and responses
+4. **Logs console** - Intercepts console methods to capture debug info
+5. **Maintains context** - Keeps the last N events as breadcrumbs
+6. **Posts errors** - Sends error data with full context to your endpoint
+
+## 📊 What Gets Captured
+
+### Error Payload Structure
+
+```json
+{
+  "type": "uncaught_exception",
+  "error": {
+    "message": "Error message",
+    "source": "file.js",
+    "lineno": 42,
+    "colno": 15,
+    "stack": "Error stack trace..."
+  },
+  "breadcrumbs": [
+    {
+      "category": "user",
+      "message": "click",
+      "data": {
+        "element": "BUTTON",
+        "id": "submit-btn",
+        "className": "btn-primary",
+        "x": 100,
+        "y": 200
+      },
+      "timestamp": "2024-01-01T12:00:00.000Z"
+    }
+  ],
+  "timestamp": "2024-01-01T12:00:00.000Z"
+}
 ```
-- **Use case**: High-performance applications
-- **Features**: Critical errors only, minimal overhead
-- **Bundle size**: ~25KB
 
-## 🔄 Reactive Object Tracking
+### Breadcrumb Categories
+
+- **`user`** - Click events, form submissions, etc.
+- **`http`** - Fetch requests, responses, and errors
+- **`console`** - Console.log, console.error, console.warn
+- **`error`** - Manual error reports
+
+## ⚙️ Configuration Options
+
+SyntropyFront uses a priority system for error handling:
 
-Track object changes in real-time using JavaScript Proxies:
+1. **Custom Error Handler** (`onError`) - Maximum flexibility
+2. **Endpoint** (`fetch`) - Automatic posting
+3. **Console** - Default fallback
+
+### Basic Configuration (Console Only)
 
 ```javascript
-// Add object for tracking
-const userProfile = SyntropyFront.addProxyObject('userProfile', {
-  name: 'John Doe',
-  preferences: { theme: 'dark' }
+syntropyFront.configure({
+  maxEvents: 50 // Number of events to keep in memory
 });
+```
 
-// Changes are automatically tracked
-userProfile.name = 'Jane Doe';
-userProfile.preferences.theme = 'light';
+### With Endpoint (Automatic Fetch)
 
-// Get tracking history
-const history = SyntropyFront.getProxyObjectHistory('userProfile');
-const currentState = SyntropyFront.getProxyObjectState('userProfile');
+```javascript
+syntropyFront.configure({
+  maxEvents: 50,
+  fetch: {
+    url: 'https://your-api.com/errors',
+    options: {
+      headers: {
+        'Authorization': 'Bearer your-token',
+        'X-API-Key': 'your-api-key',
+        'Content-Type': 'application/json'
+      },
+      mode: 'cors',
+      credentials: 'include'
+    }
+  }
+});
 ```
 
-## ⚡ Worker Architecture
-
-Offload data processing to Web Workers for non-blocking operation:
+### With Custom Error Handler (Maximum Flexibility)
 
 ```javascript
-// Worker is automatically used when enabled
-await SyntropyFront.init({
-  useWorker: true,
-  // ... other config
+syntropyFront.configure({
+  maxEvents: 50,
+  onError: (errorPayload) => {
+    // You have complete control over what to do with the error
+    
+    // Send to your API
+    fetch('https://your-api.com/errors', {
+      method: 'POST',
+      body: JSON.stringify(errorPayload)
+    });
+    
+    // Save to localStorage
+    localStorage.setItem('lastError', JSON.stringify(errorPayload));
+    
+    // Send to multiple services
+    Promise.all([
+      fetch('https://service1.com/errors', { method: 'POST', body: JSON.stringify(errorPayload) }),
+      fetch('https://service2.com/errors', { method: 'POST', body: JSON.stringify(errorPayload) })
+    ]);
+    
+    // Upload to cloud storage
+    // Send to repository
+    // Log to file
+    // Whatever you want!
+  }
 });
-
-// Check worker status
-const isAvailable = SyntropyFront.isWorkerAvailable();
-const status = SyntropyFront.getWorkerStatus();
 ```
 
-## 🛡️ Circular Reference Handling
+## 🔧 API Reference
 
-Safely serialize complex objects with circular references:
+### Core Methods
 
 ```javascript
-// Create circular reference
-const obj = { name: 'test' };
-obj.self = obj;
+// Add custom breadcrumb
+syntropyFront.addBreadcrumb('user', 'Custom action', { data: 'value' });
+
+// Send manual error
+syntropyFront.sendError(new Error('Custom error'));
+
+// Get current breadcrumbs
+const breadcrumbs = syntropyFront.getBreadcrumbs();
 
-// SyntropyFront handles this automatically
-SyntropyFront.sendError(new Error('Test'), { context: obj });
+// Clear breadcrumbs
+syntropyFront.clearBreadcrumbs();
+
+// Get statistics
+const stats = syntropyFront.getStats();
+// Returns: { breadcrumbs: 5, errors: 2, isActive: true, maxEvents: 50, endpoint: 'console' }
 ```
 
-## 📊 Breadcrumb System
+## 🎯 Extending SyntropyFront
+
+SyntropyFront captures the essentials by default, but you can extend it to capture any DOM events you want:
 
-Track user actions and application events:
+### Adding Custom Event Capture
 
 ```javascript
-// Add custom breadcrumbs
-SyntropyFront.addBreadcrumb('user', 'User clicked button', {
-  buttonId: 'submit',
-  timestamp: Date.now()
+import syntropyFront from 'syntropyfront';
+
+// Add scroll tracking
+window.addEventListener('scroll', () => {
+  syntropyFront.addBreadcrumb('user', 'scroll', {
+    scrollY: window.scrollY,
+    scrollX: window.scrollX
+  });
 });
 
-// Get breadcrumbs
-const breadcrumbs = SyntropyFront.getBreadcrumbs();
-```
+// Add form submissions
+document.addEventListener('submit', (event) => {
+  syntropyFront.addBreadcrumb('user', 'form_submit', {
+    formId: event.target.id,
+    formAction: event.target.action
+  });
+});
 
-## 🔗 Framework Integration
+// Add window resize
+window.addEventListener('resize', () => {
+  syntropyFront.addBreadcrumb('system', 'window_resize', {
+    width: window.innerWidth,
+    height: window.innerHeight
+  });
+});
 
-### React
-```javascript
-// In your main App component
-useEffect(() => {
-  SyntropyFront.init({
-    preset: 'balanced',
-    agent: { endpoint: 'https://api.com/errors' }
+// Add custom business events
+function trackPurchase(productId, amount) {
+  syntropyFront.addBreadcrumb('business', 'purchase', {
+    productId,
+    amount,
+    timestamp: new Date().toISOString()
   });
-}, []);
+}
 ```
 
-### Vue
-```javascript
-// In your main.js
-import { createApp } from 'vue';
-import App from './App.vue';
+### Common Events You Can Track
 
-const app = createApp(App);
+- **User interactions**: `click`, `scroll`, `keydown`, `focus`, `blur`
+- **Form events**: `submit`, `input`, `change`, `reset`
+- **System events**: `resize`, `online`, `offline`, `visibilitychange`
+- **Custom events**: Any business logic or user actions
+- **Performance**: `load`, `DOMContentLoaded`, timing events
 
-// Initialize SyntropyFront
-SyntropyFront.init({
-  preset: 'balanced',
-  agent: { endpoint: 'https://api.com/errors' }
-});
+## 🌐 CORS Configuration
+
+To use with your API, ensure your server allows CORS:
 
-app.mount('#app');
+```javascript
+// Express.js example
+app.use(cors({
+  origin: 'http://localhost:3000',
+  credentials: true
+}));
+
+// Or in headers
+res.setHeader('Access-Control-Allow-Origin', 'http://localhost:3000');
+res.setHeader('Access-Control-Allow-Methods', 'POST');
+res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
 ```
 
-### Angular
-```typescript
-// In your main.ts
-import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
-import { AppModule } from './app/app.module';
+## 📱 Framework Support
 
-// Initialize SyntropyFront
-SyntropyFront.init({
-  preset: 'balanced',
-  agent: { endpoint: 'https://api.com/errors' }
-});
+SyntropyFront works with any JavaScript framework:
 
-platformBrowserDynamic().bootstrapModule(AppModule);
-```
+- ✅ **React** - Works out of the box
+- ✅ **Vue** - Works out of the box  
+- ✅ **Angular** - Works out of the box
+- ✅ **Svelte** - Works out of the box
+- ✅ **Vanilla JS** - Works out of the box
 
-## 📚 API Reference
+## 🎯 Examples
 
-### Core Methods
-
-#### `SyntropyFront.init(config)`
-Initialize SyntropyFront with configuration.
+### React Example
 
-#### `SyntropyFront.addProxyObject(name, object, options)`
-Add an object for reactive tracking.
+```jsx
+import React from 'react';
+import syntropyFront from 'syntropyfront';
 
-#### `SyntropyFront.getProxyObjectHistory(name)`
-Get the change history of a tracked object.
+function App() {
+  // SyntropyFront auto-initializes on import
+  return (
+    <div>
+      <button onClick={() => console.log('Button clicked')}>
+        Click me!
+      </button>
+    </div>
+  );
+}
+```
 
-#### `SyntropyFront.addBreadcrumb(type, message, data)`
-Add a breadcrumb entry.
+### Vue Example
 
-#### `SyntropyFront.sendError(error, context)`
-Send an error with context to the backend.
+```vue
+<template>
+  <button @click="handleClick">Click me!</button>
+</template>
 
-### Configuration Options
+<script>
+import syntropyFront from 'syntropyfront';
 
-```javascript
-{
-  preset: 'balanced', // 'safe' | 'balanced' | 'debug' | 'performance'
-  agent: {
-    endpoint: 'https://api.com/errors',
-    batchTimeout: 10000,
-    batchSize: 20,
-    maxRetries: 3,
-    usePersistentBuffer: true
-  },
-  proxyTracking: {
-    enabled: true,
-    maxStates: 10,
-    trackNested: true,
-    trackArrays: true
-  },
-  useWorker: true,
-  maxBreadcrumbs: 50,
-  context: {
-    device: true,
-    window: true,
-    session: true,
-    ui: true,
-    network: true
+export default {
+  methods: {
+    handleClick() {
+      console.log('Button clicked');
+    }
   }
 }
+</script>
 ```
 
-## 🧪 Testing
+### Manual Error Reporting
 
-```bash
-# Run tests
-npm test
+```javascript
+import syntropyFront from 'syntropyfront';
 
-# Run tests in watch mode
-npm run test:watch
+try {
+  // Your code here
+} catch (error) {
+  // SyntropyFront will automatically capture this
+  throw error;
+}
 
-# Run tests with coverage
-npm run test:coverage
+// Or manually report
+syntropyFront.sendError(new Error('Something went wrong'));
 ```
 
-## 🏗️ Development
+### Extending with Custom Events
 
-```bash
-# Install dependencies
-npm install
-
-# Build the package
-npm run build
+```javascript
+import syntropyFront from 'syntropyfront';
 
-# Build in watch mode
-npm run dev
+// Add your custom event listeners
+window.addEventListener('scroll', () => {
+  syntropyFront.addBreadcrumb('user', 'scroll', {
+    scrollY: window.scrollY,
+    scrollX: window.scrollX
+  });
+});
 
-# Lint code
-npm run lint
+// Track business events
+function userCompletedCheckout(orderId, total) {
+  syntropyFront.addBreadcrumb('business', 'checkout_completed', {
+    orderId,
+    total,
+    timestamp: new Date().toISOString()
+  });
+}
 
-# Fix linting issues
-npm run lint:fix
+// Track performance
+window.addEventListener('load', () => {
+  syntropyFront.addBreadcrumb('performance', 'page_loaded', {
+    loadTime: performance.now()
+  });
+});
 ```
 
-## 📦 Build Outputs
-
-The build process generates multiple formats:
+## 🔍 Debugging
 
-- **ESM** (`dist/index.js`) - Modern ES modules
-- **CommonJS** (`dist/index.cjs`) - Node.js compatibility
-- **IIFE** (`dist/index.min.js`) - Browser-ready minified bundle
+SyntropyFront logs helpful information to the console:
 
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
+```
+🚀 SyntropyFront: Initialized with automatic capture
+✅ SyntropyFront: Configured - maxEvents: 50, endpoint: https://your-api.com/errors
+❌ Error: { type: "uncaught_exception", error: {...}, breadcrumbs: [...] }
+```
 
 ## 📄 License
 
-Apache 2.0 - see [LICENSE](LICENSE) file for details.
+Apache 2.0
 
-## 🆘 Support
+## 🤝 Contributing
 
-- 📖 [Documentation](https://github.com/Syntropysoft/syntropyfront)
-- 🐛 [Issues](https://github.com/Syntropysoft/syntropyfront/issues)
-- 💬 [Discussions](https://github.com/Syntropysoft/syntropyfront/discussions)
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ---
 
-Made with ❤️ by the SyntropyLog Team 
+**Made with ❤️ for better web observability**