sniplog 1.0.0

package/README.md

@@ -0,0 +1,294 @@
+# SnipLog SDK
+
+Enterprise-grade error tracking SDK for Node.js/Express backends and browser frontends.
+
+## Installation
+
+```bash
+npm install sniplog-sdk
+```
+
+## Usage
+
+### Node.js / Express Backend (Current Focus)
+
+#### Basic Setup
+
+```javascript
+const express = require('express');
+const SnipLog = require('sniplog-sdk');
+
+const app = express(); 
+
+// Initialize SnipLog
+const sniplog = new SnipLog({
+  endpoint: 'http://localhost:3000/api/errors',
+  projectKey: 'your-project-key',
+  autoCaptureExceptions: true, // Auto-capture uncaught exceptions
+  timeout: 5000
+});
+
+// Add request middleware (adds req.sniplog helper)
+app.use(sniplog.requestMiddleware());
+
+// Your routes here...
+
+// Add error middleware - MUST be after all routes
+app.use(sniplog.errorMiddleware());
+
+app.listen(3000);
+```
+
+#### Configuration Options
+
+```javascript
+const sniplog = new SnipLog({
+  endpoint: 'http://localhost:3000/api/errors',  // SnipLog backend URL
+  projectKey: 'your-api-key',                    // Project API key
+  autoCaptureExceptions: true,                    // Auto-capture process errors (default: true)
+  enabled: true,                                  // Enable/disable SDK (default: true)
+  timeout: 5000,                                  // Request timeout in ms (default: 5000)
+  discordWebhook: 'https://discord.com/api/webhooks/...'  // Optional: Discord webhook URL
+});
+```
+
+#### Manual Error Capture
+
+```javascript
+app.get('/api/data', async (req, res) => {
+  try {
+    const data = await fetchData();
+    res.json(data);
+  } catch (err) {
+    // Capture error with context
+    req.sniplog.captureError(err, {
+      userId: req.user?.id,
+      operation: 'fetch-data',
+      endpoint: '/api/data'
+    });
+    
+    res.status(500).json({ error: 'Failed to fetch data' });
+  }
+});
+```
+
+#### Capture Messages (Non-Errors)
+
+```javascript
+app.post('/api/users', (req, res) => {
+  req.sniplog.captureMessage('New user registration attempt', {
+    level: 'info',
+    email: req.body.email
+  });
+  
+  // ... handle registration
+});
+```
+
+#### Express Middleware Features
+
+**Request Middleware** (`sniplog.requestMiddleware()`)
+- Adds `req.sniplog.captureError()` and `req.sniplog.captureMessage()` helpers
+- Automatically includes request context (method, URL, IP, user-agent)
+
+**Error Middleware** (`sniplog.errorMiddleware()`)
+- Captures all errors that reach Express error handlers
+- Includes full request context
+- Must be placed AFTER all routes and middleware
+
+#### Auto-Capture Features
+
+When `autoCaptureExceptions: true`:
+- `uncaughtException` events are captured
+- `unhandledRejection` events are captured
+
+Each captured error includes:
+- Error message and stack trace
+- System info (Node version, OS, hostname)
+- Process ID and session ID
+- Custom metadata you provide
+
+#### Example: Complete Express App
+
+See `example-express-app.js` for a full working example.
+
+To run the example:
+
+```bash
+# Start the SnipLog backend first (in another terminal)
+cd backend
+npm start
+
+# Run the example app
+cd sdk
+node example-express-app.js
+
+# Test error capture
+curl http://localhost:4000/test-error
+```
+
+---
+
+### Browser / Frontend (Coming Soon)
+
+For frontend integration, include `browser.js` directly:
+
+```html
+<script src="/path/to/sniplog-sdk/src/browser.js"></script>
+<script>
+  SnipLog.init({
+    endpoint: 'http://localhost:3000/api/errors',
+    projectKey: 'your-project-key'
+  });
+</script>
+```
+
+The browser SDK will automatically capture:
+- `window.onerror` (script errors)
+- `unhandledrejection` (promise rejections)
+- `console.error` (optional)
+
+---
+
+## API Reference
+
+### Node.js SDK
+
+#### `new SnipLog(config)`
+
+Creates a new SnipLog instance.
+
+**Parameters:**
+- `config.endpoint` (string): SnipLog backend URL
+- `config.projectKey` (string): Your project API key
+- `config.autoCaptureExceptions` (boolean): Auto-capture process errors (default: true)
+- `config.enabled` (boolean): Enable/disable SDK (default: true)
+- `config.timeout` (number): Request timeout in ms (default: 5000)
+- `config.discordWebhook` (string): Optional Discord webhook URL for real-time notifications
+
+#### `sniplog.captureError(error, metadata)`
+
+Manually capture an error.
+
+**Parameters:**
+- `error` (Error): The error object
+- `metadata` (object): Additional context (userId, operation, etc.)
+
+#### `sniplog.captureMessage(message, metadata)`
+
+Capture a non-error message/event.
+
+**Parameters:**
+- `message` (string): The message
+- `metadata` (object): Additional context
+
+#### `sniplog.requestMiddleware()`
+
+Returns Express middleware that adds `req.sniplog` helpers.
+
+#### `sniplog.errorMiddleware()`
+
+Returns Express error handling middleware. Place after all routes.
+
+---
+
+## Discord Webhook Integration
+
+SnipLog supports real-time error notifications via Discord webhooks. Errors will be sent to both the backend database AND your Discord channel.
+
+### Setup Discord Webhook
+
+1. Open Discord and go to your server
+2. Go to **Server Settings** > **Integrations** > **Webhooks**
+3. Click **New Webhook** or **Create Webhook**
+4. Copy the **Webhook URL**
+
+### SDK Configuration
+
+```javascript
+const sniplog = new SnipLog({
+  endpoint: 'http://localhost:3000/api/errors',
+  projectKey: 'your-api-key',
+  discordWebhook: 'https://discord.com/api/webhooks/1234567890/your-webhook-token'
+});
+```
+
+### Backend Configuration
+
+Alternatively, configure Discord webhook in the backend (all projects will use it):
+
+**.env file:**
+```bash
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/1234567890/your-webhook-token
+```
+
+### Discord Message Format
+
+When an error occurs, you'll receive a Discord message like:
+
+```
+🚨 **expressError**: Cannot read property 'id' of undefined
+📅 **Time**: 10/31/2025, 3:45:12 PM
+🔗 **URL**: /api/users/123
+📍 **Method**: GET
+💻 **Host**: production-server
+👤 **User**: user-456
+
+```
+Error: Cannot read property 'id' of undefined
+    at getUserProfile (/app/routes/users.js:45:20)
+    at Layer.handle [as handle_request]
+    at next (/app/node_modules/express/lib/router/route.js:137:13)
+```
+```
+
+### Features
+
+- ✅ Real-time notifications in Discord
+- ✅ Formatted with emojis and markdown
+- ✅ Includes error message, stack trace, and metadata
+- ✅ Truncated to fit Discord's 2000 character limit
+- ✅ Works for both SDK and backend configurations
+
+---
+
+## Development
+
+### Project Structure
+
+```
+sdk/
+├── src/
+│   ├── index.js        # Auto-detects environment (Node/browser)
+│   ├── node.js         # Node.js/Express SDK
+│   └── browser.js      # Browser SDK (for future frontend use)
+├── example-express-app.js
+├── package.json
+└── README.md
+```
+
+### Testing Locally
+
+```bash
+# Link SDK locally
+cd sdk
+npm link
+
+# Use in your project
+cd your-express-app
+npm link sniplog-sdk
+```
+
+## Contributing
+
+We welcome contributions! If you'd like to improve the SDK, please open an issue or submit a pull request.
+
+For details, see our [CONTRIBUTING.md](./CONTRIBUTING.md) guide.
+
+Thanks for helping make SnipLog better!
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "sniplog",
+  "version": "1.0.0",
+  "description": "SnipLog SDK for error tracking - supports both Node.js/Express backend and browser frontend",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "echo \"No tests configured\" && exit 0"
+  },
+  "keywords": [
+    "error-tracking",
+    "crash-logging",
+    "sniplog",
+    "express-middleware",
+    "error-monitoring"
+  ],
+  "author": "ikislay, 0xgajendra",
+  "license": "MIT",
+  "files": [
+    "src/index.js",
+    "src/node.js",
+    "src/browser.js",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./node": "./src/node.js",
+    "./browser": "./src/browser.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "express": "^4.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iKislay/sniplog.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iKislay/sniplog/issues"
+  },
+  "homepage": "https://github.com/iKislay/sniplog#readme"
+}

package/src/browser.js

@@ -0,0 +1,144 @@
+/*
+	SnipLog SDK (minimal, zero-dependency)
+	Usage:
+		<script src="/path/to/snipsdk.js"></script>
+		<script>
+			SnipLog.init({ endpoint: 'http://localhost:3000/api/errors', projectKey: 'dev-project-key' });
+		</script>
+
+	The SDK captures: window.onerror, unhandledrejection, and console.error (best-effort)
+*/
+
+;(function (global) {
+	const DEFAULT_ENDPOINT = 'http://localhost:3001/api/errors';
+
+	function uuidv4() {
+		// simple UUID (RFC4122 v4-like)
+		return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+			const r = (Math.random() * 16) | 0;
+			const v = c === 'x' ? r : (r & 0x3) | 0x8;
+			return v.toString(16);
+		});
+	}
+
+	function safeStringify(obj) {
+		try {
+			return JSON.stringify(obj);
+		} catch (e) {
+			return String(obj);
+		}
+	}
+
+	function detectDevice() {
+		const ua = navigator.userAgent || '';
+		if (/Mobi|Android/i.test(ua)) return 'mobile';
+		if (/Tablet|iPad/i.test(ua)) return 'tablet';
+		return 'desktop';
+	}
+
+	function send(payload, opts) {
+		const endpoint = (opts && opts.endpoint) || DEFAULT_ENDPOINT;
+		const projectKey = (opts && opts.projectKey) || '';
+		try {
+			const body = safeStringify(payload);
+			// Use fetch if available
+			if (typeof fetch === 'function') {
+				fetch(endpoint, {
+					method: 'POST',
+					headers: {
+						'Content-Type': 'application/json',
+						Authorization: `Bearer ${projectKey}`
+					},
+					body
+				}).catch(() => {
+					// swallow network errors
+				});
+				return;
+			}
+
+			// Fallback to XHR
+			const xhr = new XMLHttpRequest();
+			xhr.open('POST', endpoint, true);
+			xhr.setRequestHeader('Content-Type', 'application/json');
+			xhr.setRequestHeader('Authorization', `Bearer ${projectKey}`);
+			xhr.send(body);
+		} catch (e) {
+			// ignore
+		}
+	}
+
+	const SnipLog = {
+		_opts: { endpoint: DEFAULT_ENDPOINT, projectKey: '' },
+		_sessionId: uuidv4(),
+		init: function (opts) {
+			this._opts = Object.assign({}, this._opts, opts || {});
+			// capture window.onerror
+			if (typeof window !== 'undefined') {
+				const self = this;
+				window.addEventListener('error', function (ev) {
+					try {
+						const e = ev.error || {};
+						const payload = {
+							message: e && e.message ? e.message : (ev.message || 'window.error'),
+							stack: (e && e.stack) || `${ev.filename}:${ev.lineno}:${ev.colno}`,
+							url: window.location.href,
+							line: ev.lineno || null,
+							column: ev.colno || null,
+							browser: { userAgent: navigator.userAgent, platform: navigator.platform },
+							device: detectDevice(),
+							sessionId: self._sessionId,
+							metadata: {},
+							ts: new Date().toISOString()
+						};
+						send(payload, self._opts);
+					} catch (ignore) {}
+				});
+
+				// unhandledrejection
+				window.addEventListener('unhandledrejection', function (ev) {
+					try {
+						const reason = ev.reason;
+						const payload = {
+							message: reason && reason.message ? reason.message : String(reason || 'unhandledrejection'),
+							stack: (reason && reason.stack) || '',
+							url: window.location.href,
+							browser: { userAgent: navigator.userAgent, platform: navigator.platform },
+							device: detectDevice(),
+							sessionId: self._sessionId,
+							metadata: { type: 'promise' },
+							ts: new Date().toISOString()
+						};
+						send(payload, self._opts);
+					} catch (ignore) {}
+				});
+
+				// console.error wrapper (best-effort, does not break app)
+				try {
+					const origConsoleError = console.error.bind(console);
+					console.error = function () {
+						try {
+							const args = Array.prototype.slice.call(arguments);
+							const payload = {
+								message: 'console.error',
+								stack: '',
+								url: window.location.href,
+								browser: { userAgent: navigator.userAgent, platform: navigator.platform },
+								device: detectDevice(),
+								sessionId: self._sessionId,
+								metadata: { console: args.map(a => (typeof a === 'object' ? safeStringify(a) : String(a))).join(' | ') },
+								ts: new Date().toISOString()
+							};
+							send(payload, self._opts);
+						} catch (ignore) {}
+						// always call original
+						origConsoleError.apply(null, arguments);
+					};
+				} catch (ignore) {}
+			}
+		}
+	};
+
+	// expose globally
+	global.SnipLog = SnipLog;
+})(typeof window !== 'undefined' ? window : this);
+

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * SnipLog SDK - Universal Entry Point
+ * Auto-detects environment and exports appropriate SDK
+ */
+
+// Detect if running in Node.js environment
+const isNode = typeof process !== 'undefined' &&
+  process.versions != null &&
+  process.versions.node != null;
+
+if (isNode) {
+  // Export Node.js version for backend/Express use
+  module.exports = require('./node');
+} else {
+  // Browser environment - this should not be reached in normal Node usage
+  // For browser, users should include browser.js directly via <script> tag
+  throw new Error('SnipLog: Use browser.js for frontend integration via <script> tag');
+}

package/src/node.js

@@ -0,0 +1,326 @@
+/**
+ * SnipLog SDK - Node.js/Express Backend Version
+ * 
+ * Usage:
+ *   const SnipLog = require('sniplog-sdk/node');
+ *   const sniplog = new SnipLog({ endpoint: 'http://localhost:3000/api/errors', projectKey: 'your-key' });
+ * 
+ *   // Express middleware (captures uncaught errors)
+ *   app.use(sniplog.errorMiddleware());
+ * 
+ *   // Manual capture
+ *   sniplog.captureError(new Error('something failed'), { userId: '123' });
+ */
+
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+const os = require('os');
+
+class SnipLog {
+  constructor(config = {}) {
+    this.endpoint = config.endpoint || 'http://localhost:3001/api/errors';
+    this.projectKey = config.projectKey || '';
+    this.webhookUrl = config.webhookUrl || config.discordWebhook || ''; // Discord webhook URL
+    this.sessionId = this._generateSessionId();
+    this.enabled = config.enabled !== false;
+    this.timeout = config.timeout || 5000;
+    
+    // Auto-capture process-level errors
+    if (config.autoCaptureExceptions !== false) {
+      this._attachGlobalHandlers();
+    }
+  }
+
+  _generateSessionId() {
+    return crypto.randomUUID ? crypto.randomUUID() : crypto.randomBytes(16).toString('hex');
+  }
+
+  _attachGlobalHandlers() {
+    // Capture uncaught exceptions
+    process.on('uncaughtException', (err) => {
+      this.captureError(err, { type: 'uncaughtException' });
+      // Allow process to continue or exit based on your policy
+    });
+
+    // Capture unhandled promise rejections
+    process.on('unhandledRejection', (reason, promise) => {
+      const err = reason instanceof Error ? reason : new Error(String(reason));
+      this.captureError(err, { type: 'unhandledRejection' });
+    });
+  }
+
+  /**
+   * Capture an error manually
+   * @param {Error} error - The error object
+   * @param {Object} metadata - Additional context
+   */
+  captureError(error, metadata = {}) {
+    if (!this.enabled) return;
+
+    const payload = this._buildPayload(error, metadata);
+    this._send(payload);
+  }
+
+  /**
+   * Capture a message (non-error event)
+   * @param {string} message - The message
+   * @param {Object} metadata - Additional context
+   */
+  captureMessage(message, metadata = {}) {
+    if (!this.enabled) return;
+
+    const payload = {
+      message: message,
+      stack: '',
+      url: metadata.url || '',
+      browser: this._getSystemInfo(),
+      device: 'server',
+      sessionId: this.sessionId,
+      metadata: { ...metadata, level: metadata.level || 'info' },
+      ts: new Date().toISOString()
+    };
+    this._send(payload);
+  }
+
+  _buildPayload(error, metadata = {}) {
+    return {
+      message: error.message || 'Unknown error',
+      stack: error.stack || '',
+      url: metadata.url || '',
+      line: this._extractLineNumber(error),
+      column: this._extractColumnNumber(error),
+      browser: this._getSystemInfo(),
+      device: 'server',
+      sessionId: this.sessionId,
+      metadata: {
+        ...metadata,
+        errorName: error.name,
+        hostname: os.hostname(),
+        pid: process.pid
+      },
+      ts: new Date().toISOString()
+    };
+  }
+
+  _extractLineNumber(error) {
+    if (!error.stack) return null;
+    const match = error.stack.match(/:(\d+)(?::(\d+))?\)?$/m);
+    return match ? parseInt(match[1], 10) : null;
+  }
+
+  _extractColumnNumber(error) {
+    if (!error.stack) return null;
+    const match = error.stack.match(/:(\d+):(\d+)\)?$/m);
+    return match ? parseInt(match[2], 10) : null;
+  }
+
+  _getSystemInfo() {
+    return {
+      userAgent: `Node.js/${process.version}`,
+      platform: `${os.platform()} ${os.release()}`,
+      arch: os.arch(),
+      nodeVersion: process.version
+    };
+  }
+
+  _send(payload) {
+    const url = new URL(this.endpoint);
+    const isHttps = url.protocol === 'https:';
+    const client = isHttps ? https : http;
+
+    const body = JSON.stringify(payload);
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'Authorization': `Bearer ${this.projectKey}`
+      },
+      timeout: this.timeout
+    };
+
+    const req = client.request(options, (res) => {
+      // Consume response to free up memory
+      res.on('data', () => {});
+      res.on('end', () => {
+        if (res.statusCode >= 400) {
+          console.warn(`[SnipLog] Error reporting failed with status ${res.statusCode}`);
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      console.warn('[SnipLog] Failed to send error:', err.message);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      console.warn('[SnipLog] Request timeout');
+    });
+
+    req.write(body);
+    req.end();
+
+    // Send to Discord webhook if configured
+    if (this.webhookUrl) {
+      this._sendToDiscord(payload);
+    }
+  }
+
+  /**
+   * Send error notification to Discord webhook
+   * @param {Object} payload - The error payload
+   */
+  _sendToDiscord(payload) {
+    try {
+      const url = new URL(this.webhookUrl);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      // Format Discord message
+      const errorMessage = this._formatDiscordMessage(payload);
+      const discordPayload = JSON.stringify({ content: errorMessage });
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(discordPayload)
+        },
+        timeout: this.timeout
+      };
+
+      const req = client.request(options, (res) => {
+        res.on('data', () => {});
+        res.on('end', () => {
+          if (res.statusCode >= 400) {
+            console.warn(`[SnipLog] Discord webhook failed with status ${res.statusCode}`);
+          }
+        });
+      });
+
+      req.on('error', (err) => {
+        console.warn('[SnipLog] Failed to send to Discord:', err.message);
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+      });
+
+      req.write(discordPayload);
+      req.end();
+    } catch (err) {
+      console.warn('[SnipLog] Discord webhook error:', err.message);
+    }
+  }
+
+  /**
+   * Format error payload for Discord message
+   * @param {Object} payload - The error payload
+   * @returns {string} Formatted Discord message
+   */
+  _formatDiscordMessage(payload) {
+    const emoji = payload.metadata?.type === 'expressError' ? '🚨' : '⚠️';
+    const errorType = payload.metadata?.type || 'Error';
+    const timestamp = new Date(payload.ts).toLocaleString();
+    
+    let message = `${emoji} **${errorType}**: ${payload.message}\n`;
+    message += `📅 **Time**: ${timestamp}\n`;
+    message += `🔗 **URL**: ${payload.url || 'N/A'}\n`;
+    
+    if (payload.metadata?.method) {
+      message += `📍 **Method**: ${payload.metadata.method}\n`;
+    }
+    
+    if (payload.metadata?.hostname) {
+      message += `💻 **Host**: ${payload.metadata.hostname}\n`;
+    }
+    
+    if (payload.metadata?.userId) {
+      message += `👤 **User**: ${payload.metadata.userId}\n`;
+    }
+    
+    // Add stack trace (truncated for Discord's limit)
+    if (payload.stack) {
+      const stackLines = payload.stack.split('\n').slice(0, 5).join('\n');
+      message += `\n\`\`\`\n${stackLines}\n\`\`\``;
+    }
+    
+    // Discord has a 2000 character limit
+    if (message.length > 1900) {
+      message = message.substring(0, 1900) + '\n... (truncated)';
+    }
+    
+    return message;
+  }
+
+  /**
+   * Express error middleware
+   * Place this AFTER all routes and other middleware
+   * 
+   * Example:
+   *   app.use(sniplog.errorMiddleware());
+   */
+  errorMiddleware() {
+    const self = this;
+    return function sniplogErrorHandler(err, req, res, next) {
+      // Capture the error
+      self.captureError(err, {
+        type: 'expressError',
+        method: req.method,
+        url: req.originalUrl || req.url,
+        ip: req.ip || req.connection.remoteAddress,
+        userAgent: req.get('user-agent'),
+        userId: req.user ? req.user.id : undefined,
+        body: req.body,
+        query: req.query,
+        params: req.params
+      });
+
+      // Pass error to next error handler
+      next(err);
+    };
+  }
+
+  /**
+   * Express request middleware (captures request context for later errors)
+   * Place this BEFORE routes
+   * 
+   * Example:
+   *   app.use(sniplog.requestMiddleware());
+   */
+  requestMiddleware() {
+    const self = this;
+    return function sniplogRequestHandler(req, res, next) {
+      // Attach a helper to capture errors within this request
+      req.sniplog = {
+        captureError: (err, metadata = {}) => {
+          self.captureError(err, {
+            ...metadata,
+            method: req.method,
+            url: req.originalUrl || req.url,
+            ip: req.ip || req.connection.remoteAddress,
+            userAgent: req.get('user-agent')
+          });
+        },
+        captureMessage: (message, metadata = {}) => {
+          self.captureMessage(message, {
+            ...metadata,
+            method: req.method,
+            url: req.originalUrl || req.url
+          });
+        }
+      };
+      next();
+    };
+  }
+}
+
+module.exports = SnipLog;