@djangocfg/monitor 2.1.229 → 2.1.231

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/monitor",
-  "version": "2.1.229",
+  "version": "2.1.231",
   "description": "Browser error and event monitoring SDK for django-cfg backends. Captures JS errors, network failures, console logs, and performance metrics.",
   "keywords": [
     "django",
@@ -83,7 +83,7 @@
     }
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.229",
+    "@djangocfg/typescript-config": "^2.1.231",
     "p-retry": "^6.2.0",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/client/hooks/useDebugMode.ts

@@ -0,0 +1,84 @@
+'use client'
+
+/**
+ * useDebugMode — shared debug mode detection hook.
+ *
+ * Logic:
+ * - development: always true (no localStorage needed)
+ * - production:
+ *   - ?debug=1 in URL → persist to localStorage, remove param from URL
+ *   - ?debug=0 in URL → clear localStorage, disable debug mode
+ *   - localStorage.__debug_mode__ === '1' → true
+ *   - otherwise → false
+ *
+ * @example
+ * const isDebug = useDebugMode()
+ */
+
+import { useEffect, useState } from 'react'
+import { isDevelopment } from '../utils/env'
+
+const LS_KEY = '__debug_mode__'
+
+function readFromStorage(): boolean {
+  try {
+    return localStorage.getItem(LS_KEY) === '1'
+  } catch {
+    return false
+  }
+}
+
+function persistToStorage(): void {
+  try {
+    localStorage.setItem(LS_KEY, '1')
+  } catch {
+    // ignore — private browsing or quota exceeded
+  }
+}
+
+function clearFromStorage(): void {
+  try {
+    localStorage.removeItem(LS_KEY)
+  } catch {
+    // ignore
+  }
+}
+
+function consumeDebugParam(): boolean | null {
+  if (typeof window === 'undefined') return null
+  const params = new URLSearchParams(window.location.search)
+  const value = params.get('debug')
+  if (value === null) return null
+
+  if (value === '1') {
+    persistToStorage()
+  } else {
+    // ?debug=0 or any other value → explicitly disable and clear stored flag
+    clearFromStorage()
+  }
+
+  params.delete('debug')
+  const newUrl = `${window.location.pathname}${params.toString() ? `?${params.toString()}` : ''}${window.location.hash}`
+  window.history.replaceState(null, '', newUrl)
+  return value === '1'
+}
+
+export function useDebugMode(): boolean {
+  // In development, always true — no side effects needed
+  if (isDevelopment) return true
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const [isDebug, setIsDebug] = useState(false)
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  useEffect(() => {
+    const fromUrl = consumeDebugParam()
+    if (fromUrl !== null) {
+      setIsDebug(fromUrl)
+      return
+    }
+    setIsDebug(readFromStorage())
+  }, [])
+
+  return isDebug
+}

package/src/client/index.ts

@@ -36,6 +36,8 @@ export type { MonitorProviderProps } from './MonitorProvider'
 export { initWindowMonitor } from './window'
 export type { WindowMonitorAPI } from './window'
 export { monitorStore } from './store'
+export { useDebugMode } from './hooks/useDebugMode'
+export { isDevelopment, isProduction, MONITOR_VERSION } from './utils/env'
 
 let flushInterval: ReturnType<typeof setInterval> | null = null
 const cleanupFns: Array<() => void> = []

package/src/client/store/index.ts

@@ -1,6 +1,7 @@
 import { createStore } from 'zustand/vanilla'
 import type { MonitorEvent, MonitorConfig } from '../../types'
 import { sendBatch } from '../transport/ingest'
+import { MONITOR_VERSION } from '../utils/env'
 
 // Circuit breaker: pause flushing after N consecutive transport failures
 const CIRCUIT_BREAKER_THRESHOLD = 3
@@ -28,6 +29,7 @@ export const monitorStore = createStore<MonitorState>((set, get) => ({
     const { config, buffer } = get()
     const maxSize = config.maxBufferSize ?? 20
     const sanitized: MonitorEvent = {
+      build_id: event.build_id ?? config.buildId ?? `sdk:${MONITOR_VERSION}`,
       ...event,
       // Enforce field size limits before buffering (last-resort backstop)
       message: event.message && event.message.length > 4997

package/src/client/utils/env.ts

@@ -0,0 +1,16 @@
+/**
+ * Environment utilities.
+ *
+ * Use these constants instead of inline process.env.NODE_ENV checks.
+ * Webpack/esbuild replaces process.env.NODE_ENV statically at build time,
+ * so these are zero-cost — they tree-shake correctly in both client and server bundles.
+ */
+
+/** True only in `next dev` / jest / vitest */
+export const isDevelopment = process.env.NODE_ENV === 'development'
+
+/** True in production builds and test environments */
+export const isProduction = process.env.NODE_ENV !== 'development'
+
+/** Package version — injected at build time via tsup define, falls back to package.json value */
+export const MONITOR_VERSION: string = (process.env.MONITOR_VERSION as string) ?? '2.1.230'

package/src/client/window.ts

@@ -16,6 +16,7 @@
 import { monitorStore } from './store'
 import { EventType, EventLevel } from '../_api'
 import { getSessionId } from './capture/session'
+import { MONITOR_VERSION } from './utils/env'
 import type { MonitorEvent } from '../types'
 
 export interface WindowMonitorAPI {
@@ -105,6 +106,8 @@ export function initWindowMonitor(): void {
     status() {
       const state = monitorStore.getState()
       console.group('[monitor] status')
+      console.log('sdk version:', MONITOR_VERSION)
+      console.log('build_id:', state.config.buildId ?? `sdk:${MONITOR_VERSION}`)
       console.log('config:', state.config)
       console.log('buffer size:', state.buffer.length)
       console.log('initialized:', state.initialized)