bugvaulty 1.0.0

package/README.md

@@ -0,0 +1,259 @@
+# BugVaulty
+
+BugVaulty automatically catches errors from Node.js, Express, and React apps, gets AI-generated fixes, and saves everything to Notion.
+
+## Install
+
+```bash
+npm install bugvaulty
+```
+
+## Init API
+
+Pass keys directly to `init()` or via environment variables for production safety.
+
+Environment variable support:
+- `BUGVAULTY_NOTION_TOKEN`
+- `BUGVAULTY_NOTION_PAGE_ID`
+- `BUGVAULTY_AI_PROVIDER`
+- `BUGVAULTY_AI_API_KEY`
+- `BUGVAULTY_CAPTURE_CONSOLE_ERRORS=true` (optional)
+
+### Option 1: Groq
+
+```js
+const bugvaulty = require('bugvaulty');
+
+bugvaulty.init({
+  notionToken: 'ntn_xxx',
+  notionPageId: 'xxx',
+  ai: {
+    provider: 'groq',
+    apiKey: 'gsk_xxx'
+  }
+});
+```
+
+### Option 2: OpenAI
+
+```js
+bugvaulty.init({
+  notionToken: 'ntn_xxx',
+  notionPageId: 'xxx',
+  ai: {
+    provider: 'openai',
+    apiKey: 'sk-xxx'
+  }
+});
+```
+
+### Option 3: Claude
+
+```js
+bugvaulty.init({
+  notionToken: 'ntn_xxx',
+  notionPageId: 'xxx',
+  ai: {
+    provider: 'claude',
+    apiKey: 'sk-ant-xxx'
+  }
+});
+```
+
+### Option 4: No AI (Notion only)
+
+```js
+bugvaulty.init({
+  notionToken: 'ntn_xxx',
+  notionPageId: 'xxx'
+});
+```
+
+## Validation behavior in `init()`
+
+- Missing `notionToken` -> throws `Error("BugVaulty: notionToken is required")`
+- Missing `notionPageId` -> throws `Error("BugVaulty: notionPageId is required")`
+- `ai.provider` set but missing `ai.apiKey` -> warns:
+  - `[BugVaulty] Warning: AI provider set but no apiKey provided. Errors will be saved without AI analysis.`
+- Unknown provider -> warns:
+  - `[BugVaulty] Warning: Unknown AI provider. Supported: groq, openai, claude`
+
+On successful init:
+
+```txt
+[BugVaulty] Initialized successfully. Tracking errors to Notion.
+```
+
+## Express integration
+
+```js
+const express = require('express');
+const bugvaulty = require('bugvaulty');
+
+const app = express();
+
+bugvaulty.init({
+  notionToken: 'ntn_xxx',
+  notionPageId: 'xxx',
+  ai: {
+    provider: 'groq',
+    apiKey: 'gsk_xxx'
+  }
+});
+
+// add after your routes
+app.use(bugvaulty.expressMiddleware());
+```
+
+BugVaulty automatically catches:
+- `process.on('uncaughtException')`
+- `process.on('unhandledRejection')`
+- Express route errors via `expressMiddleware()`
+
+## React integration
+
+```jsx
+import React from 'react';
+import { BugVaultyProvider } from 'bugvaulty/react';
+import App from './App';
+
+export default function Root() {
+  return (
+    <BugVaultyProvider
+      keys={{
+        notionToken: 'ntn_xxx',
+        notionPageId: 'xxx',
+        ai: {
+          provider: 'groq',
+          apiKey: 'gsk_xxx'
+        }
+      }}
+    >
+      <App />
+    </BugVaultyProvider>
+  );
+}
+```
+
+If a component crashes, fallback UI shows:
+
+```txt
+Something went wrong. BugVaulty has logged this error.
+```
+
+## What BugVaulty stores in Notion
+
+For each error, BugVaulty will:
+1. Detect project name from your `package.json` `name` or current folder name.
+2. Find or create a project page under your root Notion page.
+3. Create a child page with this structure:
+
+```md
+🐛 ErrorType: ErrorMessage
+
+## 📋 Error Details
+- 📅 Date
+- ⏰ Time
+- 📁 Path
+- 📍 Line
+
+## ❌ What Went Wrong
+[AI explanation]
+
+## 💡 Solution
+[AI step-by-step solution]
+
+## 🔧 Code Fix
+[code block]
+
+## 🚀 How To Avoid This
+[AI prevention tips]
+
+## ⭐ Difficulty: Beginner
+## 🏷️ Tags: #React #TypeError
+
+## 📄 Stack Trace
+[raw stack trace code block]
+```
+
+## AI providers and APIs
+
+- Groq
+  - URL: `https://api.groq.com/openai/v1/chat/completions`
+  - Model: `llama-3.3-70b-versatile`
+- OpenAI
+  - URL: `https://api.openai.com/v1/chat/completions`
+  - Model: `gpt-4o`
+- Claude (Anthropic)
+  - URL: `https://api.anthropic.com/v1/messages`
+  - Model: `claude-sonnet-4-20250514`
+
+All providers normalize to this JSON shape:
+
+```json
+{
+  "whatWentWrong": "simple explanation",
+  "solution": "step by step solution",
+  "codeFix": "corrected code",
+  "howToAvoid": "prevention tips",
+  "difficulty": "Beginner",
+  "tags": ["React", "TypeError"]
+}
+```
+
+## Reliability and safety behavior
+
+- BugVaulty never throws its own errors back to your app.
+- If AI fails, BugVaulty still logs to Notion with fallback analysis.
+- If Notion fails, BugVaulty logs an error and never crashes your app.
+- Every error is grouped automatically by project name in Notion.
+- Optional extended detection:
+  - `process.on('warning')`
+  - `process.on('multipleResolves')`
+  - `console.error` interception (enable via `capture.consoleErrors`)
+
+Console messages:
+
+```txt
+[BugVaulty] Error tracked successfully → ProjectName/ErrorType
+[BugVaulty] AI analysis failed, saving without solution.
+[BugVaulty] Failed to save to Notion: {error message}
+```
+
+## API
+
+### `init(options)`
+
+```ts
+init({
+  notionToken?: string,
+  notionPageId?: string,
+  ai?: {
+    provider: 'groq' | 'openai' | 'claude',
+    apiKey: string
+  },
+  capture?: {
+    processWarnings?: boolean,
+    multipleResolves?: boolean,
+    consoleErrors?: boolean
+  }
+})
+```
+
+If `notionToken` and `notionPageId` are omitted, BugVaulty reads:
+- `BUGVAULTY_NOTION_TOKEN`
+- `BUGVAULTY_NOTION_PAGE_ID`
+
+### `expressMiddleware()`
+Returns standard Express error middleware `(err, req, res, next)`.
+
+### `trackReactError(error, context?)`
+Used internally by `BugVaultyProvider`, but exported for advanced cases.
+
+## Notes
+
+- Keys are stored only in memory from `init()` config.
+- BugVaulty does not require manual error reporting after setup.
+- To let BugVaulty create pages under a parent page, your integration must have access to that page in Notion.
+- React integration requires `react` in your app.
+# bug-vaulty

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "bugvaulty",
+  "version": "1.0.0",
+  "description": "Automatically track errors to Notion with AI solutions",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nitin-kumar-yadav1307/bug-vaulty.git"
+  },
+  "main": "src/index.js",
+  "type": "commonjs",
+  "exports": {
+    ".": "./src/index.js",
+    "./react": "./react/index.js"
+  },
+  "files": [
+    "src",
+    "react",
+    "README.md"
+  ],
+  "keywords": [
+    "notion",
+    "error-tracking",
+    "debugging",
+    "ai",
+    "mcp"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@notionhq/client": "^2.2.15",
+    "axios": "^1.6.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.0.0"
+  }
+}

package/react/ErrorBoundary.jsx

@@ -0,0 +1,67 @@
+const React = require('react');
+const bugvaulty = require('../src');
+
+class BugVaultyProvider extends React.Component {
+	constructor(props) {
+		super(props);
+		this.state = {
+			hasError: false,
+		};
+
+		this.hasInitialized = false;
+	}
+
+	componentDidMount() {
+		this.initIfNeeded();
+	}
+
+	componentDidUpdate(prevProps) {
+		if (prevProps.keys !== this.props.keys) {
+			this.initIfNeeded();
+		}
+	}
+
+	componentDidCatch(error, info) {
+		this.setState({ hasError: true });
+
+		try {
+			bugvaulty.trackReactError(error, {
+				source: 'reactErrorBoundary',
+				componentStack: info && info.componentStack,
+			});
+		} catch (_err) {
+			// Never crash host apps.
+		}
+	}
+
+	initIfNeeded() {
+		if (this.hasInitialized) {
+			return;
+		}
+
+		try {
+			if (this.props.keys) {
+				bugvaulty.init(this.props.keys);
+				this.hasInitialized = true;
+			}
+		} catch (_err) {
+			// Never crash host apps.
+		}
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return React.createElement(
+				'div',
+				null,
+				'Something went wrong. BugVaulty has logged this error.'
+			);
+		}
+
+		return this.props.children;
+	}
+}
+
+module.exports = {
+	BugVaultyProvider,
+};

package/react/index.js

@@ -0,0 +1 @@
+module.exports = require('./ErrorBoundary.jsx');

package/src/aiService.js

@@ -0,0 +1,215 @@
+const axios = require('axios');
+const { safeJsonParse, normalizeTags } = require('./utils');
+
+const GROQ_API_URL = 'https://api.groq.com/openai/v1/chat/completions';
+const GROQ_MODEL = 'llama-3.3-70b-versatile';
+const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
+const OPENAI_MODEL = 'gpt-4o';
+const CLAUDE_API_URL = 'https://api.anthropic.com/v1/messages';
+const CLAUDE_MODEL = 'claude-sonnet-4-20250514';
+
+function fallbackAnalysis() {
+  return {
+    whatWentWrong: 'No AI provider configured',
+    solution: 'Add an AI provider in bugvaulty.init() to get solutions',
+    codeFix: '',
+    howToAvoid: '',
+    difficulty: 'Unknown',
+    tags: [],
+  };
+}
+
+function sanitizeAnalysis(raw) {
+  const base = fallbackAnalysis();
+  if (!raw || typeof raw !== 'object') {
+    return base;
+  }
+
+  return {
+    whatWentWrong: String(raw.whatWentWrong || base.whatWentWrong),
+    solution: String(raw.solution || base.solution),
+    codeFix: String(raw.codeFix || base.codeFix),
+    howToAvoid: String(raw.howToAvoid || base.howToAvoid),
+    difficulty: String(raw.difficulty || base.difficulty),
+    tags: normalizeTags(raw.tags && Array.isArray(raw.tags) ? raw.tags : base.tags),
+  };
+}
+
+function extractJsonFromText(message) {
+  if (typeof message !== 'string') {
+    return null;
+  }
+
+  const fenced = message.match(/```json\s*([\s\S]*?)\s*```/i);
+  if (fenced && fenced[1]) {
+    return fenced[1].trim();
+  }
+
+  const firstBrace = message.indexOf('{');
+  const lastBrace = message.lastIndexOf('}');
+
+  if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
+    return message.slice(firstBrace, lastBrace + 1);
+  }
+
+  return message;
+}
+
+function buildPrompt(errorData) {
+  return [
+    'Analyze this JavaScript/Node/React error and return JSON only.',
+    'Required keys: whatWentWrong, solution, codeFix, howToAvoid, difficulty, tags.',
+    'difficulty must be Beginner, Intermediate, or Advanced.',
+    'tags must be an array of short strings.',
+    '',
+    JSON.stringify(errorData, null, 2),
+  ].join('\n');
+}
+
+async function analyzeWithGroq(errorData, apiKey) {
+  const response = await axios.post(
+    GROQ_API_URL,
+    {
+      model: GROQ_MODEL,
+      temperature: 0.2,
+      messages: [
+        {
+          role: 'system',
+          content:
+            'You are an expert debugger. Always return valid JSON only with the exact requested keys.',
+        },
+        {
+          role: 'user',
+          content: buildPrompt(errorData),
+        },
+      ],
+    },
+    {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 15000,
+    }
+  );
+
+  return (
+    response &&
+    response.data &&
+    response.data.choices &&
+    response.data.choices[0] &&
+    response.data.choices[0].message &&
+    response.data.choices[0].message.content
+  );
+}
+
+async function analyzeWithOpenAI(errorData, apiKey) {
+  const response = await axios.post(
+    OPENAI_API_URL,
+    {
+      model: OPENAI_MODEL,
+      temperature: 0.2,
+      messages: [
+        {
+          role: 'system',
+          content:
+            'You are an expert debugger. Always return valid JSON only with the exact requested keys.',
+        },
+        {
+          role: 'user',
+          content: buildPrompt(errorData),
+        },
+      ],
+    },
+    {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      timeout: 15000,
+    }
+  );
+
+  return (
+    response &&
+    response.data &&
+    response.data.choices &&
+    response.data.choices[0] &&
+    response.data.choices[0].message &&
+    response.data.choices[0].message.content
+  );
+}
+
+async function analyzeWithClaude(errorData, apiKey) {
+  const response = await axios.post(
+    CLAUDE_API_URL,
+    {
+      model: CLAUDE_MODEL,
+      max_tokens: 700,
+      temperature: 0.2,
+      messages: [
+        {
+          role: 'user',
+          content: buildPrompt(errorData),
+        },
+      ],
+    },
+    {
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Type': 'application/json',
+      },
+      timeout: 15000,
+    }
+  );
+
+  const content = response && response.data && response.data.content;
+  if (Array.isArray(content) && content[0] && content[0].text) {
+    return content[0].text;
+  }
+
+  return null;
+}
+
+async function analyzeError(errorData, aiConfig) {
+  if (!aiConfig || !aiConfig.provider || !aiConfig.apiKey) {
+    return fallbackAnalysis();
+  }
+
+  const provider = String(aiConfig.provider).toLowerCase();
+  const apiKey = String(aiConfig.apiKey);
+
+  if (provider !== 'groq' && provider !== 'openai' && provider !== 'claude') {
+    return fallbackAnalysis();
+  }
+
+  try {
+    let content = null;
+
+    if (provider === 'groq') {
+      content = await analyzeWithGroq(errorData, apiKey);
+    } else if (provider === 'openai') {
+      content = await analyzeWithOpenAI(errorData, apiKey);
+    } else if (provider === 'claude') {
+      content = await analyzeWithClaude(errorData, apiKey);
+    }
+
+    const jsonText = extractJsonFromText(content || '');
+    const parsed = safeJsonParse(jsonText, null);
+
+    if (!parsed) {
+      console.warn('[BugVaulty] AI analysis failed, saving without solution.');
+      return fallbackAnalysis();
+    }
+
+    return sanitizeAnalysis(parsed);
+  } catch (err) {
+    console.warn('[BugVaulty] AI analysis failed, saving without solution.');
+    return fallbackAnalysis();
+  }
+}
+
+module.exports = {
+  analyzeError,
+};

package/src/errorCatcher.js

@@ -0,0 +1,98 @@
+const registered = {
+  processHandlers: false,
+  warningHandler: false,
+  multipleResolvesHandler: false,
+  consoleErrorPatched: false,
+};
+
+let originalConsoleError = null;
+
+function registerProcessErrorHandlers(onError, captureOptions) {
+  const options = captureOptions || {};
+
+  if (registered.processHandlers) {
+    patchConsoleError(onError, options);
+    return;
+  }
+
+  process.on('uncaughtException', (error) => {
+    safeHandle(onError, error, { source: 'uncaughtException' });
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    safeHandle(onError, reason, { source: 'unhandledRejection' });
+  });
+
+  if (options.processWarnings && !registered.warningHandler) {
+    process.on('warning', (warning) => {
+      safeHandle(onError, warning, { source: 'process.warning' });
+    });
+    registered.warningHandler = true;
+  }
+
+  if (options.multipleResolves && !registered.multipleResolvesHandler) {
+    process.on('multipleResolves', (type, _promise, reason) => {
+      safeHandle(onError, reason || new Error(`multipleResolves: ${type}`), {
+        source: 'process.multipleResolves',
+        resolveType: type,
+      });
+    });
+    registered.multipleResolvesHandler = true;
+  }
+
+  patchConsoleError(onError, options);
+  registered.processHandlers = true;
+}
+
+function patchConsoleError(onError, options) {
+  if (!options.consoleErrors || registered.consoleErrorPatched) {
+    return;
+  }
+
+  originalConsoleError = console.error;
+  console.error = function patchedConsoleError(...args) {
+    originalConsoleError.apply(console, args);
+
+    const firstError = args.find((arg) => arg instanceof Error);
+    const firstString = args.find((arg) => typeof arg === 'string');
+
+    const tracked = firstError || firstString || 'console.error called';
+    safeHandle(onError, tracked, {
+      source: 'console.error',
+      preview: firstString ? String(firstString).slice(0, 500) : '',
+    });
+  };
+
+  registered.consoleErrorPatched = true;
+}
+
+function createExpressMiddleware(onError) {
+  return function bugvaultyExpressMiddleware(err, req, _res, next) {
+    if (err) {
+      safeHandle(onError, err, {
+        source: 'express',
+        method: req && req.method,
+        route: req && (req.originalUrl || req.url),
+      });
+    }
+
+    if (typeof next === 'function') {
+      next(err);
+    }
+  };
+}
+
+function safeHandle(onError, errorLike, context) {
+  try {
+    Promise.resolve(onError(errorLike, context)).catch(() => {
+      // Silent by design.
+    });
+  } catch (_err) {
+    // Silent by design.
+  }
+}
+
+module.exports = {
+  registerProcessErrorHandlers,
+  createExpressMiddleware,
+};

package/src/index.js

@@ -0,0 +1,213 @@
+const { registerProcessErrorHandlers, createExpressMiddleware } = require('./errorCatcher');
+const { analyzeError } = require('./aiService');
+const { NotionService } = require('./notionService');
+const { normalizeError, getProjectName } = require('./utils');
+
+const SUPPORTED_PROVIDERS = ['groq', 'openai', 'claude'];
+
+const state = {
+  initialized: false,
+  config: null,
+  projectName: null,
+  notionService: null,
+  trackedFingerprint: new Map(),
+  queue: Promise.resolve(),
+};
+
+function resolveConfig(options) {
+  const input = options && typeof options === 'object' ? options : {};
+  const env = process.env || {};
+
+  const providerRaw =
+    (input.ai && input.ai.provider) || env.BUGVAULTY_AI_PROVIDER || null;
+
+  return {
+    notionToken: input.notionToken || env.BUGVAULTY_NOTION_TOKEN || null,
+    notionPageId: input.notionPageId || env.BUGVAULTY_NOTION_PAGE_ID || null,
+    ai: {
+      provider: providerRaw ? String(providerRaw).toLowerCase() : null,
+      apiKey:
+        (input.ai && input.ai.apiKey) || env.BUGVAULTY_AI_API_KEY || null,
+    },
+    capture: {
+      processWarnings:
+        input.capture && typeof input.capture.processWarnings === 'boolean'
+          ? input.capture.processWarnings
+          : true,
+      multipleResolves:
+        input.capture && typeof input.capture.multipleResolves === 'boolean'
+          ? input.capture.multipleResolves
+          : true,
+      consoleErrors:
+        input.capture && typeof input.capture.consoleErrors === 'boolean'
+          ? input.capture.consoleErrors
+          : env.BUGVAULTY_CAPTURE_CONSOLE_ERRORS === 'true',
+    },
+  };
+}
+
+function validateOptions(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('BugVaulty: notionToken is required');
+  }
+
+  if (!config.notionToken) {
+    throw new Error('BugVaulty: notionToken is required');
+  }
+
+  if (!config.notionPageId) {
+    throw new Error('BugVaulty: notionPageId is required');
+  }
+
+  const provider = config.ai && config.ai.provider ? String(config.ai.provider).toLowerCase() : null;
+  const apiKey = config.ai && config.ai.apiKey ? String(config.ai.apiKey) : '';
+
+  if (provider && !apiKey) {
+    console.warn(
+      '[BugVaulty] Warning: AI provider set but no apiKey provided. Errors will be saved without AI analysis.'
+    );
+  }
+
+  if (provider && SUPPORTED_PROVIDERS.indexOf(provider) === -1) {
+    console.warn('[BugVaulty] Warning: Unknown AI provider. Supported: groq, openai, claude');
+  }
+}
+
+function init(options) {
+  const resolvedConfig = resolveConfig(options);
+  validateOptions(resolvedConfig);
+  state.config = resolvedConfig;
+
+  state.projectName = getProjectName();
+  state.notionService = new NotionService(state.config.notionToken, state.config.notionPageId);
+
+  registerProcessErrorHandlers(trackError, state.config.capture);
+  state.initialized = true;
+
+  console.log('[BugVaulty] Initialized successfully. Tracking errors to Notion.');
+
+  return {
+    expressMiddleware,
+    trackReactError,
+  };
+}
+
+function expressMiddleware() {
+  return createExpressMiddleware(trackError);
+}
+
+function getFingerprint(normalized) {
+  return [normalized.errorType, normalized.message, normalized.filePath, normalized.lineNumber].join('|');
+}
+
+function isDuplicate(normalized) {
+  const fingerprint = getFingerprint(normalized);
+  const now = Date.now();
+  const lastSeen = state.trackedFingerprint.get(fingerprint);
+
+  if (lastSeen && now - lastSeen < 1500) {
+    return true;
+  }
+
+  state.trackedFingerprint.set(fingerprint, now);
+
+  if (state.trackedFingerprint.size > 200) {
+    const firstKey = state.trackedFingerprint.keys().next().value;
+    state.trackedFingerprint.delete(firstKey);
+  }
+
+  return false;
+}
+
+async function trackError(errorLike, context) {
+  state.queue = state.queue
+    .then(() => processTrackError(errorLike, context))
+    .catch(() => {
+      // Never allow tracking queue failures to bubble.
+    });
+
+  return state.queue;
+}
+
+function getFallbackAnalysis() {
+  return {
+    whatWentWrong: 'No AI provider configured',
+    solution: 'Add an AI provider in bugvaulty.init() to get solutions',
+    codeFix: '',
+    howToAvoid: '',
+    difficulty: 'Unknown',
+    tags: [],
+  };
+}
+
+async function processTrackError(errorLike, context) {
+  if (!state.initialized || !state.notionService) {
+    return;
+  }
+
+  const enrichedContext = {
+    ...(context || {}),
+    runtime: {
+      pid: process.pid,
+      nodeVersion: process.version,
+      platform: process.platform,
+    },
+  };
+
+  const normalized = normalizeError(errorLike, enrichedContext);
+  if (isDuplicate(normalized)) {
+    return;
+  }
+
+  let analysis;
+  try {
+    analysis = await analyzeError(
+      {
+        projectName: state.projectName,
+        errorType: normalized.errorType,
+        message: normalized.message,
+        stack: normalized.stack,
+        filePath: normalized.filePath,
+        lineNumber: normalized.lineNumber,
+        context: normalized.context,
+      },
+      state.config.ai
+    );
+  } catch (_err) {
+    analysis = getFallbackAnalysis();
+  }
+
+  const payload = {
+    ...normalized,
+    analysis,
+  };
+
+  try {
+    const projectPageId = await state.notionService.getOrCreateProjectPage(state.projectName);
+    const errorPageId = await state.notionService.createErrorPage(projectPageId, payload);
+
+    if (errorPageId) {
+      console.log(
+        `[BugVaulty] Error tracked successfully → ${state.projectName}/${normalized.errorType}`
+      );
+    } else {
+      console.warn('[BugVaulty] Failed to save to Notion: Unknown Notion error');
+    }
+  } catch (err) {
+    const message = err && err.message ? err.message : 'Unknown Notion error';
+    console.warn(`[BugVaulty] Failed to save to Notion: ${message}`);
+  }
+}
+
+function trackReactError(errorLike, context) {
+  return trackError(errorLike, {
+    source: 'react',
+    ...(context || {}),
+  });
+}
+
+module.exports = {
+  init,
+  expressMiddleware,
+  trackReactError,
+};

package/src/notionService.js

@@ -0,0 +1,184 @@
+const { Client } = require('@notionhq/client');
+
+class NotionService {
+  constructor(notionToken, rootPageId) {
+    this.notion = new Client({ auth: notionToken });
+    this.rootPageId = rootPageId;
+  }
+
+  async getOrCreateProjectPage(projectName) {
+    try {
+      const search = await this.notion.search({
+        query: projectName,
+        filter: {
+          property: 'object',
+          value: 'page',
+        },
+      });
+
+      const exactMatch = (search.results || []).find((page) => {
+        const title = this.extractPageTitle(page);
+        const parentId = page && page.parent && page.parent.page_id;
+        return title === projectName && parentId === this.rootPageId;
+      });
+
+      if (exactMatch) {
+        return exactMatch.id;
+      }
+    } catch (_err) {
+      // Continue and try create flow.
+    }
+
+    try {
+      const created = await this.notion.pages.create({
+        parent: { page_id: this.rootPageId },
+        properties: {
+          title: {
+            title: [
+              {
+                text: {
+                  content: projectName,
+                },
+              },
+            ],
+          },
+        },
+      });
+
+      return created.id;
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  extractPageTitle(page) {
+    if (!page || !page.properties) {
+      return '';
+    }
+
+    const titleProperty = Object.values(page.properties).find(
+      (property) => property && property.type === 'title'
+    );
+
+    const parts = titleProperty && Array.isArray(titleProperty.title) ? titleProperty.title : [];
+    return parts.map((part) => (part && part.plain_text ? part.plain_text : '')).join('').trim();
+  }
+
+  async createErrorPage(projectPageId, payload) {
+    if (!projectPageId) {
+      return null;
+    }
+
+    const cleanMessage = String(payload.message || 'No message').slice(0, 50);
+    const title = `🐛 ${payload.errorType}: ${cleanMessage}`;
+    const tags = Array.isArray(payload.analysis.tags) ? payload.analysis.tags : [];
+    const tagLine = tags.map((tag) => `#${String(tag).replace(/\s+/g, '')}`).join(' ');
+
+    const blocks = [
+      this.heading('📋 Error Details'),
+      this.bullet(`📅 Date: ${payload.date}`),
+      this.bullet(`⏰ Time: ${payload.time}`),
+      this.bullet(`📁 Path: ${payload.filePath || 'Unknown'}`),
+      this.bullet(`📍 Line: ${payload.lineNumber || 'Unknown'}`),
+      this.heading('❌ What Went Wrong'),
+      this.paragraph(payload.analysis.whatWentWrong),
+      this.heading('💡 Solution'),
+      this.paragraph(payload.analysis.solution),
+      this.heading('🔧 Code Fix'),
+      this.code(payload.analysis.codeFix),
+      this.heading('🚀 How To Avoid This'),
+      this.paragraph(payload.analysis.howToAvoid),
+      this.heading(`⭐ Difficulty: ${payload.analysis.difficulty}`),
+      this.heading(`🏷️ Tags: ${tagLine || 'None'}`),
+      this.heading('📄 Stack Trace'),
+      this.code(payload.stack || 'No stack trace'),
+    ];
+
+    try {
+      const response = await this.notion.pages.create({
+        parent: { page_id: projectPageId },
+        properties: {
+          title: {
+            title: [
+              {
+                text: {
+                  content: title,
+                },
+              },
+            ],
+          },
+        },
+        children: blocks,
+      });
+
+      return response.id;
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  heading(content) {
+    return {
+      object: 'block',
+      type: 'heading_2',
+      heading_2: {
+        rich_text: [
+          {
+            type: 'text',
+            text: { content: String(content || '') },
+          },
+        ],
+      },
+    };
+  }
+
+  paragraph(content) {
+    return {
+      object: 'block',
+      type: 'paragraph',
+      paragraph: {
+        rich_text: [
+          {
+            type: 'text',
+            text: { content: String(content || '') },
+          },
+        ],
+      },
+    };
+  }
+
+  bullet(content) {
+    return {
+      object: 'block',
+      type: 'bulleted_list_item',
+      bulleted_list_item: {
+        rich_text: [
+          {
+            type: 'text',
+            text: { content: String(content || '') },
+          },
+        ],
+      },
+    };
+  }
+
+  code(content) {
+    return {
+      object: 'block',
+      type: 'code',
+      code: {
+        rich_text: [
+          {
+            type: 'text',
+            text: { content: String(content || '') },
+          },
+        ],
+        language: 'javascript',
+      },
+    };
+  }
+}
+
+module.exports = {
+  NotionService,
+};

package/src/utils.js

@@ -0,0 +1,124 @@
+const fs = require('fs');
+const path = require('path');
+
+function getProjectName() {
+  const packagePath = path.join(process.cwd(), 'package.json');
+
+  try {
+    if (fs.existsSync(packagePath)) {
+      const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+      if (pkg && typeof pkg.name === 'string' && pkg.name.trim()) {
+        return pkg.name.trim();
+      }
+    }
+  } catch (_err) {
+    // Silent by design: BugVaulty should never break host apps.
+  }
+
+  return path.basename(process.cwd());
+}
+
+function parseStackTrace(stack) {
+  if (!stack || typeof stack !== 'string') {
+    return { filePath: 'Unknown', lineNumber: null };
+  }
+
+  const lines = stack.split('\n').map((line) => line.trim());
+
+  for (const line of lines) {
+    const withParens = line.match(/\((.+):(\d+):(\d+)\)/);
+    if (withParens) {
+      return {
+        filePath: withParens[1],
+        lineNumber: Number(withParens[2]),
+      };
+    }
+
+    const withoutParens = line.match(/at (.+):(\d+):(\d+)/);
+    if (withoutParens) {
+      return {
+        filePath: withoutParens[1],
+        lineNumber: Number(withoutParens[2]),
+      };
+    }
+  }
+
+  return { filePath: 'Unknown', lineNumber: null };
+}
+
+function getCurrentDateTime(dateInput) {
+  const date = dateInput instanceof Date ? dateInput : new Date();
+
+  const dateStr = date.toISOString().slice(0, 10);
+  const timeStr = date.toLocaleTimeString('en-US', {
+    hour12: true,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+
+  return { date: dateStr, time: timeStr };
+}
+
+function toError(reason) {
+  if (reason instanceof Error) {
+    return reason;
+  }
+
+  if (typeof reason === 'string') {
+    return new Error(reason);
+  }
+
+  try {
+    return new Error(JSON.stringify(reason));
+  } catch (_err) {
+    return new Error('Unknown error reason');
+  }
+}
+
+function normalizeError(inputError, context) {
+  const error = toError(inputError);
+  const stackInfo = parseStackTrace(error.stack || '');
+  const now = new Date();
+  const dateParts = getCurrentDateTime(now);
+
+  return {
+    errorType: error.name || 'Error',
+    message: error.message || 'No error message',
+    stack: error.stack || '',
+    filePath: stackInfo.filePath,
+    lineNumber: stackInfo.lineNumber,
+    date: dateParts.date,
+    time: dateParts.time,
+    timestamp: now.toISOString(),
+    context: context || {},
+  };
+}
+
+function safeJsonParse(value, fallback) {
+  try {
+    return JSON.parse(value);
+  } catch (_err) {
+    return fallback;
+  }
+}
+
+function normalizeTags(tags) {
+  if (!Array.isArray(tags)) {
+    return [];
+  }
+
+  return tags
+    .map((tag) => String(tag).trim())
+    .filter(Boolean)
+    .slice(0, 8);
+}
+
+module.exports = {
+  getProjectName,
+  parseStackTrace,
+  getCurrentDateTime,
+  normalizeError,
+  safeJsonParse,
+  normalizeTags,
+};