Add integration examples and fix code review issues

Co-authored-by: BaseMax <2658040+BaseMax@users.noreply.github.com>

Author: Copilot

examples/README.md

@@ -0,0 +1,167 @@
+# Error Vault Integration Examples
+
+This directory contains example client implementations for integrating Error Vault with applications in various programming languages.
+
+## Directory Structure
+
+```
+examples/
+├── go/          # Go client example
+├── nodejs/      # Node.js client example
+└── python/      # Python client example
+```
+
+## Go Example
+
+### Setup
+
+```bash
+cd examples/go
+go mod init example
+go get github.com/BaseMax/go-error-vault
+go run client.go
+```
+
+### Usage
+
+```go
+client := NewErrorVaultClient(
+    "http://localhost:8080/api/errors",
+    "my-go-app",
+    "1.0.0",
+)
+
+err := fmt.Errorf("something went wrong")
+metadata := map[string]interface{}{
+    "user_id": "12345",
+}
+
+client.ReportError(err, metadata)
+```
+
+## Node.js Example
+
+### Setup
+
+```bash
+cd examples/nodejs
+npm install
+node client.js
+```
+
+### Usage
+
+```javascript
+const ErrorVaultClient = require('./client');
+
+const client = new ErrorVaultClient(
+  'http://localhost:8080/api/errors',
+  'my-node-app',
+  '1.0.0'
+);
+
+try {
+  // Your code
+} catch (error) {
+  await client.reportError(error, {
+    user_id: '12345'
+  });
+}
+```
+
+## Python Example
+
+### Setup
+
+```bash
+cd examples/python
+pip install -r requirements.txt
+python client.py
+```
+
+### Usage
+
+```python
+from client import ErrorVaultClient
+
+client = ErrorVaultClient(
+    url='http://localhost:8080/api/errors',
+    app_name='my-python-app',
+    app_version='1.0.0'
+)
+
+try:
+    # Your code
+except Exception as error:
+    client.report_error(error, {
+        'user_id': '12345'
+    })
+```
+
+## File-Based Integration
+
+You can also report errors by dropping JSON files into the Error Vault watch directory:
+
+```bash
+# Default watch directory
+mkdir -p ~/.errorvault/incoming
+
+# Create an error report
+cat > ~/.errorvault/incoming/error.json << EOF
+{
+  "message": "Database connection timeout",
+  "stack": "at db.connect() line 42",
+  "app_name": "myapp",
+  "app_version": "1.0.0",
+  "metadata": {
+    "database": "users",
+    "timeout": 5000
+  }
+}
+EOF
+```
+
+The file will be automatically processed within 5 seconds (default collection interval) and moved to `.processed/` directory.
+
+## Integration Best Practices
+
+1. **Always include metadata**: Add contextual information like user IDs, request IDs, or environment details
+2. **Don't block on errors**: Report errors asynchronously to avoid impacting application performance
+3. **Handle reporting failures gracefully**: Log locally if Error Vault is unavailable
+4. **Include stack traces**: Full stack traces help with debugging and grouping
+5. **Set appropriate app versions**: This helps track when issues were introduced
+
+## Error Report Format
+
+All errors should follow this JSON schema:
+
+```json
+{
+  "message": "Error description",
+  "stack": "Stack trace (optional but recommended)",
+  "app_name": "Your application name",
+  "app_version": "1.0.0 (optional)",
+  "metadata": {
+    "key": "value",
+    "custom": "fields"
+  }
+}
+```
+
+## Testing Your Integration
+
+1. Start Error Vault server:
+   ```bash
+   errorvault server
+   ```
+
+2. Run your client example
+
+3. Verify the error was received:
+   ```bash
+   errorvault list
+   ```
+
+## Support
+
+For more information, see the main [README](../README.md).

examples/go/client.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"runtime/debug"
+)
+
+// ErrorReport represents an error to be sent to Error Vault
+type ErrorReport struct {
+	Message    string                 `json:"message"`
+	Stack      string                 `json:"stack"`
+	AppName    string                 `json:"app_name"`
+	AppVersion string                 `json:"app_version"`
+	Metadata   map[string]interface{} `json:"metadata,omitempty"`
+}
+
+// ErrorVaultClient is a client for reporting errors to Error Vault
+type ErrorVaultClient struct {
+	url        string
+	appName    string
+	appVersion string
+}
+
+// NewErrorVaultClient creates a new Error Vault client
+func NewErrorVaultClient(url, appName, appVersion string) *ErrorVaultClient {
+	return &ErrorVaultClient{
+		url:        url,
+		appName:    appName,
+		appVersion: appVersion,
+	}
+}
+
+// ReportError sends an error to Error Vault
+func (c *ErrorVaultClient) ReportError(err error, metadata map[string]interface{}) error {
+	report := ErrorReport{
+		Message:    err.Error(),
+		Stack:      string(debug.Stack()),
+		AppName:    c.appName,
+		AppVersion: c.appVersion,
+		Metadata:   metadata,
+	}
+
+	data, jsonErr := json.Marshal(report)
+	if jsonErr != nil {
+		return fmt.Errorf("failed to marshal error report: %w", jsonErr)
+	}
+
+	resp, httpErr := http.Post(c.url, "application/json", bytes.NewBuffer(data))
+	if httpErr != nil {
+		return fmt.Errorf("failed to send error report: %w", httpErr)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusCreated {
+		return fmt.Errorf("unexpected status code: %d", resp.StatusCode)
+	}
+
+	return nil
+}
+
+// Example usage
+func main() {
+	// Initialize the client
+	client := NewErrorVaultClient(
+		"http://localhost:8080/api/errors",
+		"my-go-app",
+		"1.0.0",
+	)
+
+	// Simulate an error
+	err := fmt.Errorf("database connection failed")
+
+	// Report the error with metadata
+	metadata := map[string]interface{}{
+		"user_id":  "12345",
+		"endpoint": "/api/users",
+		"method":   "GET",
+	}
+
+	if reportErr := client.ReportError(err, metadata); reportErr != nil {
+		log.Printf("Failed to report error: %v", reportErr)
+	} else {
+		log.Println("Error reported successfully")
+	}
+}

examples/nodejs/client.js

@@ -0,0 +1,82 @@
+const axios = require('axios');
+
+/**
+ * Error Vault client for Node.js applications
+ */
+class ErrorVaultClient {
+  constructor(url, appName, appVersion) {
+    this.url = url;
+    this.appName = appName;
+    this.appVersion = appVersion;
+  }
+
+  /**
+   * Report an error to Error Vault
+   * @param {Error} error - The error object
+   * @param {Object} metadata - Additional metadata
+   */
+  async reportError(error, metadata = {}) {
+    try {
+      const report = {
+        message: error.message,
+        stack: error.stack,
+        app_name: this.appName,
+        app_version: this.appVersion,
+        metadata: metadata
+      };
+
+      const response = await axios.post(this.url, report);
+      console.log('Error reported:', response.data);
+      return response.data;
+    } catch (err) {
+      console.error('Failed to report error:', err.message);
+      throw err;
+    }
+  }
+}
+
+// Example usage
+async function main() {
+  // Initialize the client
+  const client = new ErrorVaultClient(
+    'http://localhost:8080/api/errors',
+    'my-node-app',
+    '1.0.0'
+  );
+
+  // Set up global error handlers
+  process.on('uncaughtException', async (error) => {
+    console.error('Uncaught exception:', error);
+    await client.reportError(error, {
+      type: 'uncaughtException'
+    });
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', async (reason, promise) => {
+    const error = new Error(`Unhandled Rejection: ${reason}`);
+    console.error('Unhandled rejection:', error);
+    await client.reportError(error, {
+      type: 'unhandledRejection',
+      promise: promise.toString()
+    });
+  });
+
+  // Simulate an error
+  try {
+    throw new Error('Something went wrong in the application');
+  } catch (error) {
+    await client.reportError(error, {
+      user_id: '12345',
+      endpoint: '/api/users',
+      method: 'POST'
+    });
+  }
+}
+
+// Run the example
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+module.exports = ErrorVaultClient;

examples/nodejs/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "errorvault-example",
+  "version": "1.0.0",
+  "description": "Example Node.js integration with Error Vault",
+  "main": "client.js",
+  "scripts": {
+    "start": "node client.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  }
+}