@jhits/plugin-telemetry 0.0.1

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@jhits/plugin-telemetry",
+    "version": "0.0.1",
+    "description": "System logging and telemetry utilities for the JHITS ecosystem",
+    "publishConfig": {
+      "access": "public"
+    },
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+      ".": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "./server": {
+        "types": "./src/server.ts",
+        "default": "./src/server.ts"
+      },
+      "./api/route": {
+        "types": "./src/api/route.ts",
+        "default": "./src/api/route.ts"
+      },
+      "./api/handler": {
+        "types": "./src/api/handler.ts",
+        "default": "./src/api/handler.ts"
+      },
+      "./utils/logCleaner": {
+        "types": "./src/utils/logCleaner.ts",
+        "default": "./src/utils/logCleaner.ts"
+      }
+    },
+    "dependencies": {
+      "@jhits/plugin-core": "^0.0.1"
+    },
+    "peerDependencies": {
+      "next": ">=15.0.0",
+      "react": ">=18.0.0",
+      "react-dom": ">=18.0.0"
+    },
+    "devDependencies": {
+      "@types/node": "^20.19.27",
+      "@types/react": "^19",
+      "@types/react-dom": "^19",
+      "next": "16.1.1",
+      "react": "19.2.3",
+      "react-dom": "19.2.3",
+      "typescript": "^5"
+    },
+    "files": [
+      "src",
+      "package.json"
+    ]
+  }

package/src/TelemetryProvider.tsx

@@ -0,0 +1,33 @@
+/**
+ * Telemetry Provider
+ * React context provider for telemetry functionality
+ */
+"use client";
+
+import React, { createContext, useContext, ReactNode } from 'react';
+import { TelemetryService as ITelemetryService } from './types';
+import { telemetryService } from './TelemetryService';
+
+const TelemetryContext = createContext<ITelemetryService | null>(null);
+
+export interface TelemetryProviderProps {
+    children: ReactNode;
+}
+
+export const TelemetryProvider: React.FC<TelemetryProviderProps> = ({ children }) => {
+    return (
+        <TelemetryContext.Provider value={telemetryService}>
+            {children}
+        </TelemetryContext.Provider>
+    );
+};
+
+export const useTelemetry = (): ITelemetryService => {
+    const context = useContext(TelemetryContext);
+    if (!context) {
+        // Fallback to service directly if context is not available
+        return telemetryService;
+    }
+    return context;
+};
+

package/src/TelemetryService.ts

@@ -0,0 +1,337 @@
+/**
+ * Telemetry Service
+ * Core service for logging and managing telemetry data
+ * Uses backend file-based logging with buffering
+ */
+import { TelemetryEntry, TelemetryCategory, TelemetryService as ITelemetryService } from './types';
+
+const API_ENDPOINT = '/api/dashboard/telemetry';
+const BUFFER_INTERVAL_MS = 5000; // Send buffered logs every 5 seconds
+const MAX_BUFFER_SIZE = 50; // Max entries to buffer before forcing send
+
+class TelemetryServiceClass implements ITelemetryService {
+    private buffer: TelemetryEntry[] = [];
+    private flushTimer: NodeJS.Timeout | null = null;
+    private defaultContext: string = 'system';
+
+    private generateId(): string {
+        return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+
+    /**
+     * Safe JSON stringify that handles circular references and DOM/React elements
+     * Uses WeakSet to track seen objects and returns "[Circular]" for repeated references
+     */
+    private safeStringify(value: any, space?: number): string {
+        const seen = new WeakSet();
+        const isDOMNode = (val: any): boolean => {
+            return (
+                typeof Node !== 'undefined' && val instanceof Node ||
+                typeof Element !== 'undefined' && val instanceof Element ||
+                (val && typeof val === 'object' && 'nodeType' in val && 'nodeName' in val)
+            );
+        };
+        const isReactElement = (val: any): boolean => {
+            return (
+                val &&
+                typeof val === 'object' &&
+                (val.$$typeof === Symbol.for('react.element') ||
+                 val.$$typeof === Symbol.for('react.portal') ||
+                 Object.keys(val).some(key => key.startsWith('__react') || key.startsWith('_react')))
+            );
+        };
+        const isEvent = (val: any): boolean => {
+            return (
+                val &&
+                typeof val === 'object' &&
+                (val instanceof Event ||
+                 (typeof Event !== 'undefined' && val.constructor?.name === 'Event') ||
+                 (val.target && val.currentTarget && val.type))
+            );
+        };
+
+        const replacer = (key: string, val: any): any => {
+            // Skip React internal keys
+            if (key.startsWith('__react') || key.startsWith('_react')) {
+                return '[React Internal]';
+            }
+
+            // Handle null/undefined
+            if (val === null || val === undefined) {
+                return val;
+            }
+
+            // Handle DOM nodes
+            if (isDOMNode(val)) {
+                return '[DOM Node]';
+            }
+
+            // Handle React elements
+            if (isReactElement(val)) {
+                return '[React Element]';
+            }
+
+            // Handle Events
+            if (isEvent(val)) {
+                return `[Event: ${val.type || 'unknown'}]`;
+            }
+
+            // Handle functions
+            if (typeof val === 'function') {
+                return `[Function: ${val.name || 'anonymous'}]`;
+            }
+
+            // Handle circular references
+            if (typeof val === 'object') {
+                if (seen.has(val)) {
+                    return '[Circular]';
+                }
+                seen.add(val);
+            }
+
+            return val;
+        };
+
+        try {
+            return JSON.stringify(value, replacer, space);
+        } catch (error) {
+            // Fallback if stringify still fails
+            return JSON.stringify({
+                error: 'Failed to stringify',
+                message: error instanceof Error ? error.message : String(error),
+                type: typeof value,
+            }, null, space);
+        }
+    }
+
+    /**
+     * Get safe JSON serializer that handles circular references and React Fiber nodes
+     */
+    /**
+     * Send entries to backend API
+     * CRITICAL: Uses safe serializer to prevent circular JSON errors
+     */
+    private async sendToBackend(entries: TelemetryEntry[], useBeacon: boolean = false): Promise<void> {
+        if (entries.length === 0) return;
+
+        try {
+            // SAFE SERIALIZER to prevent Circular structure errors
+            const getCircularReplacer = () => {
+                const seen = new WeakSet();
+                return (key: string, value: any) => {
+                    if (typeof value === "object" && value !== null) {
+                        if (seen.has(value)) return "[Circular]";
+                        seen.add(value);
+                        // Strip out DOM elements and React internals
+                        if (value instanceof Node) return `[DOM: ${value.nodeName}]`;
+                        if (key.startsWith('__react')) return "[ReactInternal]";
+                    }
+                    return value;
+                };
+            };
+
+            const data = JSON.stringify(entries, getCircularReplacer());
+            
+            if (navigator.sendBeacon && useBeacon) {
+                const blob = new Blob([data], { type: 'application/json' });
+                if (navigator.sendBeacon(API_ENDPOINT, blob)) return;
+            }
+
+            const response = await fetch(API_ENDPOINT, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: data,
+            });
+
+            if (!response.ok) throw new Error(`Status ${response.status}`);
+        } catch (error) {
+            console.error('[TelemetryService] Serialization or Network failure:', error);
+        }
+    }
+
+    /**
+     * Schedule a flush of the buffer
+     */
+    private scheduleFlush(): void {
+        // Clear existing timer
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+        }
+
+        // Schedule new flush
+        this.flushTimer = setTimeout(() => {
+            this.flush();
+        }, BUFFER_INTERVAL_MS);
+    }
+
+    /**
+     * Flush buffer to backend immediately
+     */
+    async flush(useBeacon: boolean = false): Promise<void> {
+        if (this.buffer.length === 0) return;
+
+        const entriesToSend = [...this.buffer];
+        this.buffer = [];
+
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+
+        await this.sendToBackend(entriesToSend, useBeacon);
+    }
+
+    log(category: TelemetryCategory, message: string, data?: any, context?: string): void {
+        const entry: TelemetryEntry = {
+            id: this.generateId(),
+            timestamp: Date.now(),
+            category,
+            message,
+            data: data || {},
+            context: context || this.defaultContext,
+        };
+
+        // Add to buffer
+        this.buffer.push(entry);
+
+        // Also log to console for immediate visibility (less intrusive, emoji-coded breadcrumbs)
+        // Only log in development or if explicitly enabled
+        if (process.env.NODE_ENV === 'development' || process.env.TELEMETRY_VERBOSE === 'true') {
+            const emoji = category === 'DRAG_DROP' ? '📦' : category === 'STATE' ? '📊' : category === 'ERROR' ? '❌' : '🎨';
+            // Use safeStringify for console logs too to prevent circular reference errors
+            const safeData = data ? this.safeStringify(data) : '';
+            console.log(`${emoji} [${entry.context}] ${message}`, safeData || '');
+        }
+
+        // Send immediately if ERROR, otherwise schedule flush
+        if (category === 'ERROR') {
+            this.flush();
+        } else if (this.buffer.length >= MAX_BUFFER_SIZE) {
+            // Force flush if buffer is getting large
+            this.flush();
+        } else {
+            // Schedule regular flush
+            this.scheduleFlush();
+        }
+    }
+
+    error(message: string, error: Error | unknown, data?: any, context?: string): void {
+        const errorObj = error instanceof Error ? error : new Error(String(error));
+        const entry: TelemetryEntry = {
+            id: this.generateId(),
+            timestamp: Date.now(),
+            category: 'ERROR',
+            message,
+            data: {
+                ...data,
+                errorMessage: errorObj.message,
+                errorName: errorObj.name,
+            },
+            stack: errorObj.stack,
+            context: context || this.defaultContext,
+        };
+
+        // Add to buffer
+        this.buffer.push(entry);
+
+        // Also log to console for immediate visibility (errors always shown, but with safe stringify)
+        // Use safeStringify to prevent circular reference errors in console
+        const safeData = data ? this.safeStringify(data) : '';
+        console.error(`❌ [${entry.context}] ${message}`, error instanceof Error ? error.message : String(error), safeData || '');
+
+        // Errors are sent immediately
+        this.flush();
+    }
+
+    setContext(context: string): void {
+        this.defaultContext = context;
+    }
+
+    exportLogs(): void {
+        // Flush any pending logs first
+        this.flush().then(() => {
+            // Inform user that logs are on the server
+            alert('Telemetry logs are stored on the server at: logs/editor-debug.log\n\nCheck the server logs directory for the file.');
+        }).catch(() => {
+            alert('Telemetry logs are stored on the server. Check logs/editor-debug.log on the server.');
+        });
+    }
+
+    clearLogs(): void {
+        // Clear the buffer (logs are already on server, can't clear server logs from client)
+        this.buffer = [];
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Less intrusive console log
+        if (process.env.NODE_ENV === 'development' || process.env.TELEMETRY_VERBOSE === 'true') {
+            console.log('🧹 Telemetry buffer cleared');
+        }
+    }
+
+    getLogs(): TelemetryEntry[] {
+        // Return current buffer (server logs are not accessible from client)
+        return [...this.buffer];
+    }
+}
+
+// Initialize global error handlers
+const initializeGlobalErrorHandlers = (service: TelemetryServiceClass): void => {
+    // Capture window.onerror
+    const originalOnError = window.onerror;
+    window.onerror = (message, source, lineno, colno, error) => {
+        service.error(
+            'Global Error Handler',
+            error || new Error(String(message)),
+            {
+                message: String(message),
+                source: String(source),
+                lineno,
+                colno,
+            }
+        );
+        if (originalOnError) {
+            return originalOnError(message, source, lineno, colno, error);
+        }
+        return false;
+    };
+
+    // Capture unhandled promise rejections
+    window.addEventListener('unhandledrejection', (event) => {
+        service.error(
+            'Unhandled Promise Rejection',
+            event.reason,
+            {
+                // Don't include the promise object itself (can cause circular references)
+                reason: event.reason instanceof Error ? event.reason.message : String(event.reason),
+            }
+        );
+    });
+};
+
+// Initialize unload handler for flushing logs
+const initializeUnloadHandler = (service: TelemetryServiceClass): void => {
+    // Flush logs on page unload using sendBeacon
+    window.addEventListener('beforeunload', () => {
+        service.flush(true); // Use sendBeacon for unload
+    });
+
+    // Also handle visibility change (tab switch, minimize, etc.)
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+            service.flush(true); // Use sendBeacon when tab becomes hidden
+        }
+    });
+};
+
+// Create singleton instance
+export const telemetryService = new TelemetryServiceClass();
+
+// Initialize global error handlers and unload handler
+if (typeof window !== 'undefined') {
+    initializeGlobalErrorHandlers(telemetryService);
+    initializeUnloadHandler(telemetryService);
+}
+
+

package/src/api/handler.ts

@@ -0,0 +1,275 @@
+/**
+ * Telemetry API Handler
+ * Plugin-mounted API handler for telemetry logging
+ * Compatible with Next.js API routes and Express
+ * 
+ * IMPORTANT: This file should ONLY be imported in server-side API routes.
+ * Do NOT import this in client-side code.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import fs from 'fs/promises';
+import path from 'path';
+
+const LOG_DIR = path.join(process.cwd(), 'logs');
+const LOG_FILE = path.join(LOG_DIR, 'jhits-system.log');
+const OLD_LOG_FILE = path.join(LOG_DIR, 'jhits-system.old.log');
+const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_BATCH_SIZE = 100; // Maximum entries per request
+const MAX_ENTRY_SIZE = 100 * 1024; // 100KB per entry
+
+interface TelemetryEntry {
+    id: string;
+    timestamp: number;
+    category: string;
+    message: string;
+    data: any;
+    stack?: string;
+    context?: string;
+    userId?: string;
+    sessionId?: string;
+}
+
+/**
+ * Ensure logs directory exists
+ */
+async function ensureLogDir(): Promise<void> {
+    try {
+        await fs.access(LOG_DIR);
+    } catch {
+        await fs.mkdir(LOG_DIR, { recursive: true });
+    }
+}
+
+/**
+ * Check log file size and rotate if necessary
+ */
+async function rotateLogIfNeeded(): Promise<void> {
+    try {
+        const stats = await fs.stat(LOG_FILE);
+        if (stats.size > MAX_LOG_SIZE) {
+            // Rename current log to old log
+            try {
+                await fs.rename(LOG_FILE, OLD_LOG_FILE);
+            } catch (error: any) {
+                // If old log exists, remove it first
+                if (error.code === 'EEXIST' || error.code === 'ENOENT') {
+                    try {
+                        await fs.unlink(OLD_LOG_FILE);
+                        await fs.rename(LOG_FILE, OLD_LOG_FILE);
+                    } catch {
+                        // If still fails, just overwrite
+                        await fs.copyFile(LOG_FILE, OLD_LOG_FILE);
+                        await fs.unlink(LOG_FILE);
+                    }
+                } else {
+                    throw error;
+                }
+            }
+        }
+    } catch (error: any) {
+        // If file doesn't exist, that's fine - we'll create it
+        if (error.code !== 'ENOENT') {
+            console.error('[Telemetry Handler] Error checking log size:', error);
+        }
+    }
+}
+
+/**
+ * Format log entry as single-line JSON
+ */
+function formatLogEntry(entry: TelemetryEntry): string {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const context = entry.context || 'unknown';
+    const userId = entry.userId || 'anonymous';
+    const sessionId = entry.sessionId || 'unknown';
+    
+    // Sanitize data to prevent log injection
+    const sanitizedData = typeof entry.data === 'object' 
+        ? JSON.stringify(entry.data).replace(/\n/g, '\\n').replace(/\r/g, '\\r')
+        : String(entry.data);
+    
+    const stackStr = entry.stack ? ` "stack":"${entry.stack.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"` : '';
+    
+    return `[${timestamp}] [${context}] [${userId}] [${sessionId}] [${entry.category}] ${entry.message} ${sanitizedData}${stackStr}\n`;
+}
+
+/**
+ * Validate and sanitize telemetry entry
+ */
+function validateEntry(entry: any): TelemetryEntry | null {
+    // Basic validation
+    if (!entry || typeof entry !== 'object') {
+        return null;
+    }
+
+    // Check required fields
+    if (!entry.id || !entry.timestamp || !entry.category || !entry.message) {
+        return null;
+    }
+
+    // Size check to prevent log injection attacks
+    const entrySize = JSON.stringify(entry).length;
+    if (entrySize > MAX_ENTRY_SIZE) {
+        console.warn('[Telemetry Handler] Entry too large, skipping:', entry.id);
+        return null;
+    }
+
+    // Sanitize string fields
+    return {
+        id: String(entry.id).substring(0, 100),
+        timestamp: Number(entry.timestamp),
+        category: String(entry.category).substring(0, 50),
+        message: String(entry.message).substring(0, 500),
+        data: entry.data || {},
+        stack: entry.stack ? String(entry.stack).substring(0, 5000) : undefined,
+        context: entry.context ? String(entry.context).substring(0, 100) : undefined,
+        userId: entry.userId ? String(entry.userId).substring(0, 100) : undefined,
+        sessionId: entry.sessionId ? String(entry.sessionId).substring(0, 100) : undefined,
+    };
+}
+
+/**
+ * Extract user/session info from request headers or cookies
+ */
+function extractContext(request: NextRequest): { userId?: string; sessionId?: string } {
+    // Try to get user ID from headers (custom header)
+    const userId = request.headers.get('x-user-id') || 
+                   request.headers.get('x-userid') ||
+                   undefined;
+    
+    // Try to get session ID from headers or cookies
+    const sessionId = request.headers.get('x-session-id') ||
+                      request.headers.get('x-sessionid') ||
+                      request.cookies.get('sessionId')?.value ||
+                      request.cookies.get('session')?.value ||
+                      undefined;
+
+    return { userId, sessionId };
+}
+
+/**
+ * Next.js API Route Handler
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+    try {
+        // Ensure log directory exists
+        await ensureLogDir();
+        
+        // Rotate log if needed
+        await rotateLogIfNeeded();
+        
+        // Extract context from request
+        const { userId, sessionId } = extractContext(request);
+        
+        // Parse request body
+        const body = await request.json();
+        
+        // Handle single entry or batch of entries
+        const entries = Array.isArray(body) ? body : [body];
+        
+        // Rate limiting: Check batch size
+        if (entries.length > MAX_BATCH_SIZE) {
+            return NextResponse.json(
+                { success: false, error: `Batch size exceeds maximum of ${MAX_BATCH_SIZE}` },
+                { status: 400 }
+            );
+        }
+        
+        // Validate and sanitize entries
+        const validEntries: TelemetryEntry[] = [];
+        for (const entry of entries) {
+            const validated = validateEntry(entry);
+            if (validated) {
+                // Add context from request if not present in entry
+                if (!validated.userId && userId) {
+                    validated.userId = userId;
+                }
+                if (!validated.sessionId && sessionId) {
+                    validated.sessionId = sessionId;
+                }
+                validEntries.push(validated);
+            }
+        }
+        
+        if (validEntries.length === 0) {
+            return NextResponse.json(
+                { success: false, error: 'No valid entries to log' },
+                { status: 400 }
+            );
+        }
+        
+        // Format and append each entry
+        const logLines = validEntries.map(formatLogEntry).join('');
+        await fs.appendFile(LOG_FILE, logLines, 'utf8');
+        
+        return NextResponse.json({ 
+            success: true, 
+            logged: validEntries.length,
+            rejected: entries.length - validEntries.length
+        });
+    } catch (error) {
+        console.error('[Telemetry Handler] Error writing log:', error);
+        return NextResponse.json(
+            { success: false, error: 'Failed to write log' },
+            { status: 500 }
+        );
+    }
+}
+
+/**
+ * Express-compatible handler
+ * For use with Express.js or other Node.js frameworks
+ */
+export function telemetryHandler(req: any, res: any): void {
+    // This is a simplified version for Express
+    // In a real Express setup, you'd need to adapt the NextRequest/NextResponse types
+    const handler = async () => {
+        try {
+            await ensureLogDir();
+            await rotateLogIfNeeded();
+            
+            const body = req.body;
+            const entries = Array.isArray(body) ? body : [body];
+            
+            if (entries.length > MAX_BATCH_SIZE) {
+                return res.status(400).json({ 
+                    success: false, 
+                    error: `Batch size exceeds maximum of ${MAX_BATCH_SIZE}` 
+                });
+            }
+            
+            const validEntries: TelemetryEntry[] = [];
+            for (const entry of entries) {
+                const validated = validateEntry(entry);
+                if (validated) {
+                    // Extract from Express request
+                    validated.userId = validated.userId || req.headers['x-user-id'] || req.user?.id;
+                    validated.sessionId = validated.sessionId || req.headers['x-session-id'] || req.session?.id;
+                    validEntries.push(validated);
+                }
+            }
+            
+            if (validEntries.length === 0) {
+                return res.status(400).json({ 
+                    success: false, 
+                    error: 'No valid entries to log' 
+                });
+            }
+            
+            const logLines = validEntries.map(formatLogEntry).join('');
+            await fs.appendFile(LOG_FILE, logLines, 'utf8');
+            
+            res.json({ 
+                success: true, 
+                logged: validEntries.length,
+                rejected: entries.length - validEntries.length
+            });
+        } catch (error) {
+            console.error('[Telemetry Handler] Error writing log:', error);
+            res.status(500).json({ success: false, error: 'Failed to write log' });
+        }
+    };
+    
+    handler();
+}
+

package/src/api/route.ts

@@ -0,0 +1,9 @@
+/**
+ * Telemetry API Route Handler
+ * Server-only wrapper for the telemetry handler
+ * This file should ONLY be used in Next.js API routes
+ */
+import { POST as handlerPOST } from './handler';
+
+export { handlerPOST as POST };
+

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Plugin Telemetry
+ * Standalone telemetry package for JHITS v2
+ * 
+ * NOTE: API handler is NOT exported here to prevent client-side bundling.
+ * Import the handler directly from '@jhits/plugin-telemetry/api/handler' in server-side API routes only.
+ */
+export { TelemetryProvider, useTelemetry } from './TelemetryProvider';
+export { telemetryService } from './TelemetryService';
+export type { TelemetryEntry, TelemetryCategory, TelemetryService } from './types';
+export { summarizeBlock, summarizeBlocks, createBlockActionPayload } from './utils/logCleaner';
+export type { BlockSummary, MoveBlockData, DeleteBlockData, InsertBlockData } from './utils/logCleaner';
+

package/src/server.ts

@@ -0,0 +1,237 @@
+/**
+ * Server-only exports for @jhits/plugin-telemetry
+ * These exports should only be used in server-side code (API routes, server components)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import fs from 'fs/promises';
+import path from 'path';
+
+const LOG_DIR = path.join(process.cwd(), 'logs');
+const LOG_FILE = path.join(LOG_DIR, 'jhits-system.log');
+const OLD_LOG_FILE = path.join(LOG_DIR, 'jhits-system.old.log');
+const MAX_LOG_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_BATCH_SIZE = 100; // Maximum entries per request
+const MAX_ENTRY_SIZE = 100 * 1024; // 100KB per entry
+
+interface TelemetryEntry {
+    id: string;
+    timestamp: number;
+    category: string;
+    message: string;
+    data: any;
+    stack?: string;
+    context?: string;
+    userId?: string;
+    sessionId?: string;
+}
+
+/**
+ * Ensure logs directory exists
+ */
+async function ensureLogDir(): Promise<void> {
+    try {
+        await fs.access(LOG_DIR);
+    } catch {
+        await fs.mkdir(LOG_DIR, { recursive: true });
+    }
+}
+
+/**
+ * Check log file size and rotate if necessary
+ */
+async function rotateLogIfNeeded(): Promise<void> {
+    try {
+        const stats = await fs.stat(LOG_FILE);
+        if (stats.size > MAX_LOG_SIZE) {
+            // Rename current log to old log
+            try {
+                await fs.rename(LOG_FILE, OLD_LOG_FILE);
+            } catch (error: any) {
+                // If old log exists, remove it first
+                if (error.code === 'EEXIST' || error.code === 'ENOENT') {
+                    try {
+                        await fs.unlink(OLD_LOG_FILE);
+                        await fs.rename(LOG_FILE, OLD_LOG_FILE);
+                    } catch {
+                        // If still fails, just overwrite
+                        await fs.copyFile(LOG_FILE, OLD_LOG_FILE);
+                        await fs.unlink(LOG_FILE);
+                    }
+                } else {
+                    throw error;
+                }
+            }
+        }
+    } catch (error: any) {
+        // If file doesn't exist, that's fine - we'll create it
+        if (error.code !== 'ENOENT') {
+            console.error('[Telemetry Handler] Error checking log size:', error);
+        }
+    }
+}
+
+/**
+ * Format log entry as single-line JSON (or pretty-printed in debug mode)
+ * CRITICAL: Single-line format for easier grep/tailing, but pretty-printed if debug flag is on
+ */
+function formatLogEntry(entry: TelemetryEntry, debug: boolean = false): string {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const context = entry.context || 'unknown';
+    const userId = entry.userId || 'anonymous';
+    const sessionId = entry.sessionId || 'unknown';
+    
+    // Check for debug mode via environment variable
+    const isDebugMode = debug || process.env.TELEMETRY_DEBUG === 'true';
+    
+    if (isDebugMode) {
+        // Pretty-printed format for debugging
+        const logObject = {
+            timestamp,
+            context,
+            userId,
+            sessionId,
+            category: entry.category,
+            message: entry.message,
+            data: entry.data,
+            ...(entry.stack && { stack: entry.stack })
+        };
+        return JSON.stringify(logObject, null, 2) + '\n';
+    } else {
+        // Single-line JSON format for production (easier grep/tailing)
+        const sanitizedData = typeof entry.data === 'object' 
+            ? JSON.stringify(entry.data).replace(/\n/g, '\\n').replace(/\r/g, '\\r')
+            : String(entry.data);
+        
+        const stackStr = entry.stack ? ` "stack":"${entry.stack.replace(/"/g, '\\"').replace(/\n/g, '\\n')}"` : '';
+        
+        return `[${timestamp}] [${context}] [${userId}] [${sessionId}] [${entry.category}] ${entry.message} ${sanitizedData}${stackStr}\n`;
+    }
+}
+
+/**
+ * Validate and sanitize telemetry entry
+ */
+function validateEntry(entry: any): TelemetryEntry | null {
+    // Basic validation
+    if (!entry || typeof entry !== 'object') {
+        return null;
+    }
+
+    // Check required fields
+    if (!entry.id || !entry.timestamp || !entry.category || !entry.message) {
+        return null;
+    }
+
+    // Size check to prevent log injection attacks
+    const entrySize = JSON.stringify(entry).length;
+    if (entrySize > MAX_ENTRY_SIZE) {
+        console.warn('[Telemetry Handler] Entry too large, skipping:', entry.id);
+        return null;
+    }
+
+    // Sanitize string fields
+    return {
+        id: String(entry.id).substring(0, 100),
+        timestamp: Number(entry.timestamp),
+        category: String(entry.category).substring(0, 50),
+        message: String(entry.message).substring(0, 500),
+        data: entry.data || {},
+        stack: entry.stack ? String(entry.stack).substring(0, 5000) : undefined,
+        context: entry.context ? String(entry.context).substring(0, 100) : undefined,
+        userId: entry.userId ? String(entry.userId).substring(0, 100) : undefined,
+        sessionId: entry.sessionId ? String(entry.sessionId).substring(0, 100) : undefined,
+    };
+}
+
+/**
+ * Extract user/session info from request headers or cookies
+ */
+function extractContext(request: NextRequest): { userId?: string; sessionId?: string } {
+    // Try to get user ID from headers (custom header)
+    const userId = request.headers.get('x-user-id') || 
+                   request.headers.get('x-userid') ||
+                   undefined;
+    
+    // Try to get session ID from headers or cookies
+    const sessionId = request.headers.get('x-session-id') ||
+                      request.headers.get('x-sessionid') ||
+                      request.cookies.get('sessionId')?.value ||
+                      request.cookies.get('session')?.value ||
+                      undefined;
+
+    return { userId, sessionId };
+}
+
+/**
+ * Telemetry Handler
+ * Server-only function for processing telemetry data
+ * 
+ * @param data - Telemetry entry or array of entries
+ * @param context - Optional context with userId and sessionId
+ * @returns Result object with success status and logging information
+ */
+export async function telemetryHandler(
+    data: any,
+    context?: { userId?: string; sessionId?: string }
+): Promise<{ success: boolean; logged?: number; rejected?: number; error?: string }> {
+    try {
+        // Ensure log directory exists
+        await ensureLogDir();
+        
+        // Rotate log if needed
+        await rotateLogIfNeeded();
+        
+        // Handle single entry or batch of entries
+        const entries = Array.isArray(data) ? data : [data];
+        
+        // Rate limiting: Check batch size
+        if (entries.length > MAX_BATCH_SIZE) {
+            return {
+                success: false,
+                error: `Batch size exceeds maximum of ${MAX_BATCH_SIZE}`
+            };
+        }
+        
+        // Validate and sanitize entries
+        const validEntries: TelemetryEntry[] = [];
+        for (const entry of entries) {
+            const validated = validateEntry(entry);
+            if (validated) {
+                // Add context if provided
+                if (context?.userId && !validated.userId) {
+                    validated.userId = context.userId;
+                }
+                if (context?.sessionId && !validated.sessionId) {
+                    validated.sessionId = context.sessionId;
+                }
+                validEntries.push(validated);
+            }
+        }
+        
+        if (validEntries.length === 0) {
+            return {
+                success: false,
+                error: 'No valid entries to log'
+            };
+        }
+        
+        // Format and append each entry (check for debug mode)
+        const debugMode = process.env.TELEMETRY_DEBUG === 'true';
+        const logLines = validEntries.map(entry => formatLogEntry(entry, debugMode)).join('');
+        await fs.appendFile(LOG_FILE, logLines, 'utf8');
+        
+        return {
+            success: true,
+            logged: validEntries.length,
+            rejected: entries.length - validEntries.length
+        };
+    } catch (error) {
+        console.error('[Telemetry Handler] Error writing log:', error);
+        return {
+            success: false,
+            error: 'Failed to write log',
+        };
+    }
+}
+

package/src/types/next.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Type declarations for Next.js server types
+ * This package is designed to be used in Next.js applications where these types are available
+ */
+
+declare module 'next/server' {
+    export interface NextRequest extends Request {
+        cookies: {
+            get(name: string): { value: string } | undefined;
+        };
+        headers: Headers;
+    }
+    
+    export class NextResponse extends Response {
+        static json(body: any, init?: ResponseInit): NextResponse;
+    }
+}
+

package/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Telemetry Types
+ * Type definitions for the telemetry system
+ */
+
+export type TelemetryCategory = 'DRAG_DROP' | 'STATE' | 'ERROR' | 'UI';
+
+export interface TelemetryEntry {
+    id: string;
+    timestamp: number;
+    category: TelemetryCategory;
+    message: string;
+    data: any;
+    stack?: string;
+    context?: string;
+    userId?: string;
+    sessionId?: string;
+}
+
+export interface TelemetryService {
+    log: (category: TelemetryCategory, message: string, data?: any, context?: string) => void;
+    error: (message: string, error: Error | unknown, data?: any, context?: string) => void;
+    exportLogs: () => void;
+    clearLogs: () => void;
+    getLogs: () => TelemetryEntry[];
+    flush: () => Promise<void>;
+    setContext: (context: string) => void;
+}
+

package/src/utils/logCleaner.ts

@@ -0,0 +1,111 @@
+/**
+ * Log Cleaner Utilities
+ * Optimizes telemetry payloads by summarizing large data structures
+ */
+
+// Use a generic interface to avoid circular dependencies
+interface BlockLike {
+    id: string | number;
+    type?: string;
+    nestedBlocks?: BlockLike[];
+}
+
+/**
+ * Summarized block representation for telemetry
+ */
+export interface BlockSummary {
+    id: string;
+    type: string;
+    childCount: number;
+}
+
+/**
+ * Summarize a single block to reduce log payload size
+ * Only includes essential information: id, type, and child count
+ */
+export function summarizeBlock(block: BlockLike | { id: string; type: string; nestedBlocks?: any[] }): BlockSummary {
+    return {
+        id: String(block.id),
+        type: String(block.type || 'unknown'),
+        childCount: Array.isArray(block.nestedBlocks) ? block.nestedBlocks.length : 0
+    };
+}
+
+/**
+ * Summarize an array of blocks to reduce log payload size
+ * Recursively summarizes nested blocks up to a maximum depth
+ */
+export function summarizeBlocks(
+    blocks: BlockLike[] | undefined,
+    maxDepth: number = 2
+): BlockSummary[] {
+    if (!Array.isArray(blocks) || blocks.length === 0) {
+        return [];
+    }
+
+    return blocks.map(block => {
+        const summary: BlockSummary = {
+            id: String(block.id),
+            type: String(block.type || 'unknown'),
+            childCount: Array.isArray(block.nestedBlocks) ? block.nestedBlocks.length : 0
+        };
+
+        // Optionally include nested summaries if depth allows (for debugging)
+        if (maxDepth > 0 && block.nestedBlocks && block.nestedBlocks.length > 0) {
+            // Only include nested summaries in debug mode
+            // For production, just the childCount is sufficient
+        }
+
+        return summary;
+    });
+}
+
+/**
+ * Extract action-specific data for telemetry
+ */
+export interface MoveBlockData {
+    blockId: string;
+    fromParent: string | null;
+    toParent: string | null;
+    fromIndex?: number;
+    toIndex: number;
+}
+
+export interface DeleteBlockData {
+    blockId: string;
+    blockType: string;
+    parentId: string | null;
+}
+
+export interface InsertBlockData {
+    newBlockType: string;
+    parentId: string | null;
+    index: number;
+    newBlockId?: string;
+}
+
+/**
+ * Create optimized telemetry payload for block operations
+ * Removes full block arrays and only includes essential action data
+ */
+export function createBlockActionPayload(
+    actionType: 'MOVE_BLOCK' | 'DELETE_BLOCK' | 'INSERT_BLOCK',
+    data: MoveBlockData | DeleteBlockData | InsertBlockData,
+    options?: {
+        includeBlocks?: boolean; // Only for CRITICAL_ERROR
+        affectedBlockId?: string;
+    }
+): Record<string, any> {
+    const payload: Record<string, any> = {
+        actionType,
+        ...data
+    };
+
+    // Only include full blocks for critical errors
+    if (options?.includeBlocks && options.affectedBlockId) {
+        payload.affectedBlockId = options.affectedBlockId;
+    }
+
+    return payload;
+}
+