@djangocfg/monitor 2.1.216

package/src/_api/generated/cfg_monitor/validation-events.ts

@@ -0,0 +1,135 @@
+// @ts-nocheck
+// Auto-generated by DjangoCFG - see CLAUDE.md
+/**
+ * Zod Validation Events - Browser CustomEvent integration
+ *
+ * Dispatches browser CustomEvents when Zod validation fails, allowing
+ * React/frontend apps to listen and handle validation errors globally.
+ *
+ * @example
+ * ```typescript
+ * // In your React app
+ * window.addEventListener('zod-validation-error', (event) => {
+ *   const { operation, path, method, error, response } = event.detail;
+ *   console.error(`Validation failed for ${method} ${path}`, error);
+ *   // Show toast notification, log to Sentry, etc.
+ * });
+ * ```
+ */
+
+import type { ZodError } from 'zod'
+
+/**
+ * Validation error event detail
+ */
+export interface ValidationErrorDetail {
+  /** Operation/function name that failed validation */
+  operation: string
+  /** API endpoint path */
+  path: string
+  /** HTTP method */
+  method: string
+  /** Zod validation error */
+  error: ZodError
+  /** Raw response data that failed validation */
+  response: any
+  /** Timestamp of the error */
+  timestamp: Date
+}
+
+/**
+ * Custom event type for Zod validation errors
+ */
+export type ValidationErrorEvent = CustomEvent<ValidationErrorDetail>
+
+/**
+ * Dispatch a Zod validation error event.
+ *
+ * Only dispatches in browser environment (when window is defined).
+ * Safe to call in Node.js/SSR - will be a no-op.
+ *
+ * @param detail - Validation error details
+ */
+export function dispatchValidationError(detail: ValidationErrorDetail): void {
+  // Check if running in browser
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    const event = new CustomEvent<ValidationErrorDetail>('zod-validation-error', {
+      detail,
+      bubbles: true,
+      cancelable: false,
+    })
+
+    window.dispatchEvent(event)
+  } catch (error) {
+    // Silently fail - validation event dispatch should never crash the app
+    console.warn('Failed to dispatch validation error event:', error)
+  }
+}
+
+/**
+ * Add a global listener for Zod validation errors.
+ *
+ * @param callback - Function to call when validation error occurs
+ * @returns Cleanup function to remove the listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onValidationError(({ operation, error }) => {
+ *   toast.error(`Validation failed in ${operation}`);
+ *   logToSentry(error);
+ * });
+ *
+ * // Later, remove listener
+ * cleanup();
+ * ```
+ */
+export function onValidationError(
+  callback: (detail: ValidationErrorDetail) => void
+): () => void {
+  if (typeof window === 'undefined') {
+    // Return no-op cleanup function for SSR
+    return () => {}
+  }
+
+  const handler = (event: Event) => {
+    if (event instanceof CustomEvent) {
+      callback(event.detail)
+    }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+
+  // Return cleanup function
+  return () => {
+    window.removeEventListener('zod-validation-error', handler)
+  }
+}
+
+/**
+ * Format Zod error for logging/display.
+ *
+ * @param error - Zod validation error
+ * @returns Formatted error message
+ */
+export function formatZodError(error: ZodError): string {
+  const issues = error.issues.map((issue, index) => {
+    const path = issue.path.join('.') || 'root'
+    const parts = [`${index + 1}. ${path}: ${issue.message}`]
+
+    if ('expected' in issue && issue.expected) {
+      parts.push(`   Expected: ${issue.expected}`)
+    }
+
+    if ('received' in issue && issue.received) {
+      parts.push(`   Received: ${issue.received}`)
+    }
+
+    return parts.join('\n')
+  })
+
+  return issues.join('\n')
+}

package/src/_api/index.ts

@@ -0,0 +1,6 @@
+export { monitorApi, configureMonitorApi, BaseClient } from './BaseClient'
+export type { FrontendEventIngestRequest, IngestBatchRequest } from './generated/cfg_monitor/monitor/models'
+export { FrontendEventIngestRequestEventType as EventType, FrontendEventIngestRequestLevel as EventLevel } from './generated/cfg_monitor/enums'
+
+/** Ingest path — matches the generated client. Single source of truth for sendBeacon fallback. */
+export const INGEST_PATH = '/cfg/monitor/ingest/'

package/src/client/capture/console.ts

@@ -0,0 +1,72 @@
+import { computeFingerprint } from './fingerprint'
+import { getSessionId } from './session'
+import { monitorStore } from '../store'
+import { EventType, EventLevel } from '../../_api'
+import type { FrontendEventIngestRequestEventType, FrontendEventIngestRequestLevel } from '../../_api/generated/cfg_monitor/enums'
+
+type ConsoleLevel = 'warn' | 'error'
+
+const levelMap: Record<ConsoleLevel, FrontendEventIngestRequestLevel> = {
+  warn: EventLevel.WARN,
+  error: EventLevel.ERROR,
+}
+const typeMap: Record<ConsoleLevel, FrontendEventIngestRequestEventType> = {
+  warn: EventType.WARNING,
+  error: EventType.ERROR,
+}
+
+function stringify(args: unknown[]): string {
+  return args.map((a) => {
+    if (typeof a === 'string') return a
+    if (a instanceof Error) return a.message
+    try { return JSON.stringify(a) } catch { return String(a) }
+  }).join(' ')
+}
+
+async function captureConsoleEvent(level: ConsoleLevel, args: unknown[]) {
+  try {
+    const message = stringify(args)
+    const url = typeof window !== 'undefined' ? window.location.href : ''
+    const fingerprint = await computeFingerprint(message, '', url)
+    const { config } = monitorStore.getState()
+    monitorStore.getState().push({
+      event_type: typeMap[level],
+      level: levelMap[level],
+      message,
+      url,
+      fingerprint,
+      session_id: getSessionId(),
+      user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+      project_name: config.project,
+      environment: config.environment,
+    })
+  } catch { /* never crash */ }
+}
+
+export function installConsoleCapture(): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  try {
+    const g = globalThis as Record<string, unknown>
+    if (g.consola && typeof (g.consola as { addReporter?: unknown }).addReporter === 'function') {
+      const consolaInst = g.consola as {
+        addReporter: (r: unknown) => void
+        removeReporter: (r: unknown) => void
+      }
+      const reporter = {
+        log(logObj: { level: number; args: unknown[] }) {
+          if (logObj.level === 1) captureConsoleEvent('error', logObj.args)
+          else if (logObj.level === 2) captureConsoleEvent('warn', logObj.args)
+        },
+      }
+      consolaInst.addReporter(reporter)
+      return () => consolaInst.removeReporter(reporter)
+    }
+  } catch { /* consola not available */ }
+
+  const origWarn = console.warn.bind(console)
+  const origError = console.error.bind(console)
+  console.warn = (...args: unknown[]) => { origWarn(...args); captureConsoleEvent('warn', args) }
+  console.error = (...args: unknown[]) => { origError(...args); captureConsoleEvent('error', args) }
+  return () => { console.warn = origWarn; console.error = origError }
+}

package/src/client/capture/fingerprint.ts

@@ -0,0 +1,27 @@
+function simpleHash(str: string): string {
+  let hash = 0
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) - hash + str.charCodeAt(i)
+    hash = hash & hash
+  }
+  return Math.abs(hash).toString(16).padStart(8, '0')
+}
+
+export async function computeFingerprint(
+  message: string,
+  stack: string,
+  url: string,
+): Promise<string> {
+  const raw = `${message}|${stack}|${url}`
+  if (typeof crypto !== 'undefined' && crypto.subtle) {
+    try {
+      const data = new TextEncoder().encode(raw)
+      const buf = await crypto.subtle.digest('SHA-256', data)
+      return Array.from(new Uint8Array(buf))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, 64)
+    } catch { /* fall through */ }
+  }
+  return simpleHash(raw)
+}

package/src/client/capture/js-errors.ts

@@ -0,0 +1,70 @@
+import { computeFingerprint } from './fingerprint'
+import { getSessionId } from './session'
+import { monitorStore } from '../store'
+import { EventType, EventLevel } from '../../_api'
+
+export function installJsErrorCapture(): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  const onError = async (
+    message: string | Event,
+    source?: string,
+    lineno?: number,
+    colno?: number,
+    error?: Error,
+  ) => {
+    try {
+      const msg = typeof message === 'string' ? message : String(message)
+      const stack = error?.stack ?? `at ${source}:${lineno}:${colno}`
+      const url = window.location.href
+      const fingerprint = await computeFingerprint(msg, stack, url)
+      const { config } = monitorStore.getState()
+      monitorStore.getState().push({
+        event_type: EventType.JS_ERROR,
+        level: EventLevel.ERROR,
+        message: msg,
+        stack_trace: stack,
+        url,
+        fingerprint,
+        session_id: getSessionId(),
+        user_agent: navigator.userAgent,
+        project_name: config.project,
+        environment: config.environment,
+      })
+    } catch { /* never crash */ }
+  }
+
+  const onUnhandledRejection = async (e: PromiseRejectionEvent) => {
+    try {
+      const reason = e.reason
+      const msg = reason instanceof Error ? reason.message
+        : typeof reason === 'string' ? reason
+        : 'Unhandled promise rejection'
+      const stack = reason instanceof Error ? (reason.stack ?? '') : ''
+      const url = window.location.href
+      const fingerprint = await computeFingerprint(msg, stack, url)
+      const { config } = monitorStore.getState()
+      monitorStore.getState().push({
+        event_type: EventType.JS_ERROR,
+        level: EventLevel.ERROR,
+        message: msg,
+        stack_trace: stack,
+        url,
+        fingerprint,
+        session_id: getSessionId(),
+        user_agent: navigator.userAgent,
+        project_name: config.project,
+        environment: config.environment,
+      })
+    } catch { /* never crash */ }
+  }
+
+  const errHandler = (e: ErrorEvent) => onError(e.message, e.filename, e.lineno, e.colno, e.error)
+  window.addEventListener('error', errHandler)
+  window.addEventListener('unhandledrejection', onUnhandledRejection)
+
+  return () => {
+    window.removeEventListener('error', errHandler)
+    window.removeEventListener('unhandledrejection', onUnhandledRejection)
+  }
+}

package/src/client/capture/network.ts

@@ -0,0 +1,47 @@
+import { getSessionId } from './session'
+import { monitorStore } from '../store'
+import { EventType, EventLevel } from '../../_api'
+
+export async function monitoredFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+  const method = (init?.method ?? 'GET').toUpperCase()
+
+  try {
+    const response = await fetch(input, init)
+    if (!response.ok) {
+      const { config } = monitorStore.getState()
+      monitorStore.getState().push({
+        event_type: EventType.NETWORK_ERROR,
+        level: response.status >= 500 ? EventLevel.ERROR : EventLevel.WARN,
+        message: `HTTP ${response.status} ${response.statusText} — ${method} ${url}`,
+        url: typeof window !== 'undefined' ? window.location.href : '',
+        http_status: response.status,
+        http_method: method,
+        http_url: url,
+        session_id: getSessionId(),
+        user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+        project_name: config.project,
+        environment: config.environment,
+      })
+    }
+    return response
+  } catch (err) {
+    const { config } = monitorStore.getState()
+    monitorStore.getState().push({
+      event_type: EventType.NETWORK_ERROR,
+      level: EventLevel.ERROR,
+      message: err instanceof Error ? err.message : `Network error — ${method} ${url}`,
+      url: typeof window !== 'undefined' ? window.location.href : '',
+      http_method: method,
+      http_url: url,
+      session_id: getSessionId(),
+      user_agent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+      project_name: config.project,
+      environment: config.environment,
+    })
+    throw err
+  }
+}

package/src/client/capture/session.ts

@@ -0,0 +1,33 @@
+const SESSION_KEY = 'fm_session_id'
+const COOKIE_MAX_AGE = 60 * 60 * 24 * 365
+
+function generateUUID(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID()
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16)
+  })
+}
+
+function setCookie(name: string, value: string): void {
+  if (typeof document === 'undefined') return
+  document.cookie = `${name}=${value}; path=/; SameSite=Lax; max-age=${COOKIE_MAX_AGE}`
+}
+
+export function getSessionId(): string {
+  if (typeof localStorage === 'undefined') return ''
+  let id = localStorage.getItem(SESSION_KEY)
+  if (!id) {
+    id = generateUUID()
+    localStorage.setItem(SESSION_KEY, id)
+    setCookie(SESSION_KEY, id)
+  }
+  return id
+}
+
+export function ensureSessionCookie(): void {
+  const id = getSessionId()
+  if (id) setCookie(SESSION_KEY, id)
+}

package/src/client/capture/validation.ts

@@ -0,0 +1,38 @@
+import { getSessionId } from './session'
+import { monitorStore } from '../store'
+import { EventType, EventLevel } from '../../_api'
+
+interface ValidationErrorDetail {
+  operation: string
+  path: string
+  method: string
+  error: { message: string }
+}
+
+export function installValidationCapture(): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  const handler = (event: Event) => {
+    if (!(event instanceof CustomEvent)) return
+    try {
+      const detail = event.detail as ValidationErrorDetail
+      const { config } = monitorStore.getState()
+      monitorStore.getState().push({
+        event_type: EventType.WARNING,
+        level: EventLevel.WARN,
+        message: `Zod validation error in ${detail.operation}: ${detail.error?.message ?? 'unknown'}`,
+        url: window.location.href,
+        http_method: detail.method,
+        http_url: detail.path,
+        session_id: getSessionId(),
+        user_agent: navigator.userAgent,
+        project_name: config.project,
+        environment: config.environment,
+        extra: { operation: detail.operation, path: detail.path, method: detail.method },
+      })
+    } catch { /* never crash */ }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+  return () => window.removeEventListener('zod-validation-error', handler)
+}

package/src/client/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @djangocfg/monitor/client
+ *
+ * Browser-side monitor. Use in 'use client' components only.
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ * import { useEffect } from 'react'
+ * import { FrontendMonitor } from '@djangocfg/monitor/client'
+ *
+ * export function MonitorProvider() {
+ *   useEffect(() => {
+ *     FrontendMonitor.init({ project: 'my-app', environment: process.env.NODE_ENV })
+ *     return () => FrontendMonitor.destroy()
+ *   }, [])
+ *   return null
+ * }
+ * ```
+ */
+
+import { installJsErrorCapture } from './capture/js-errors'
+import { installConsoleCapture } from './capture/console'
+import { installValidationCapture } from './capture/validation'
+import { ensureSessionCookie } from './capture/session'
+import { monitorStore } from './store'
+import { configureMonitorApi } from '../_api'
+import type { MonitorConfig, MonitorEvent } from '../types'
+
+export type { MonitorConfig, MonitorEvent, EventType, EventLevel } from '../types'
+export { monitoredFetch } from './capture/network'
+export { getSessionId } from './capture/session'
+
+let flushInterval: ReturnType<typeof setInterval> | null = null
+const cleanupFns: Array<() => void> = []
+
+export const FrontendMonitor = {
+  init(config: MonitorConfig = {}): void {
+    if (typeof window === 'undefined') return
+
+    if (config.baseUrl) configureMonitorApi(config.baseUrl)
+    monitorStore.getState().setConfig(config)
+    ensureSessionCookie()
+
+    if (config.captureJsErrors !== false) cleanupFns.push(installJsErrorCapture())
+    if (config.captureConsole !== false) cleanupFns.push(installConsoleCapture())
+    cleanupFns.push(installValidationCapture())
+
+    const interval = config.flushInterval ?? 5000
+    flushInterval = setInterval(() => monitorStore.getState().flush(), interval)
+
+    const onHide = () => { if (document.visibilityState === 'hidden') monitorStore.getState().flush(true) }
+    window.addEventListener('visibilitychange', onHide)
+    window.addEventListener('beforeunload', () => monitorStore.getState().flush(true))
+
+    if (config.debug) console.info('[FrontendMonitor] initialized', config)
+  },
+
+  capture(event: MonitorEvent): void {
+    monitorStore.getState().push(event)
+  },
+
+  flush(): void {
+    monitorStore.getState().flush()
+  },
+
+  destroy(): void {
+    if (flushInterval !== null) { clearInterval(flushInterval); flushInterval = null }
+    cleanupFns.forEach((fn) => fn())
+    cleanupFns.length = 0
+  },
+}

package/src/client/store/index.ts

@@ -0,0 +1,41 @@
+import { createStore } from 'zustand/vanilla'
+import type { MonitorEvent, MonitorConfig } from '../../types'
+import { sendBatch } from '../transport/ingest'
+
+interface MonitorState {
+  config: MonitorConfig
+  buffer: MonitorEvent[]
+  initialized: boolean
+  push: (event: MonitorEvent) => void
+  flush: (useBeacon?: boolean) => void
+  setConfig: (config: MonitorConfig) => void
+}
+
+export const monitorStore = createStore<MonitorState>((set, get) => ({
+  config: {},
+  buffer: [],
+  initialized: false,
+
+  push(event) {
+    const { config, buffer } = get()
+    const maxSize = config.maxBufferSize ?? 20
+    const next = [...buffer, event]
+    set({ buffer: next })
+
+    if (next.length >= maxSize || event.level === 'error') {
+      get().flush()
+    }
+  },
+
+  flush(useBeacon = false) {
+    const { buffer } = get()
+    if (buffer.length === 0) return
+    const batch = buffer.slice(0, 50)
+    set({ buffer: buffer.slice(50) })
+    sendBatch({ events: batch }, useBeacon)
+  },
+
+  setConfig(config) {
+    set({ config, initialized: true })
+  },
+}))

package/src/client/transport/ingest.ts

@@ -0,0 +1,31 @@
+import { monitorApi } from '../../_api'
+import { API, MemoryStorageAdapter, KeepAliveFetchAdapter } from '../../_api/generated/cfg_monitor'
+import type { IngestBatchRequest } from '../../_api'
+
+/** Separate API instance with KeepAliveFetchAdapter — survives page unload */
+const monitorApiBeacon = new API('', {
+  storage: new MemoryStorageAdapter(),
+  httpClient: new KeepAliveFetchAdapter(),
+})
+
+export function syncBeaconBaseUrl(): void {
+  monitorApiBeacon.setBaseUrl(monitorApi.getBaseUrl())
+}
+
+export async function sendBatch(
+  batch: IngestBatchRequest,
+  useBeacon = false,
+): Promise<void> {
+  if (batch.events.length === 0) return
+
+  try {
+    if (useBeacon) {
+      syncBeaconBaseUrl()
+      await monitorApiBeacon.monitor.ingestCreate(batch)
+    } else {
+      await monitorApi.monitor.ingestCreate(batch)
+    }
+  } catch {
+    // Transport errors silently ignored — monitoring must never crash the app
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @djangocfg/monitor
+ *
+ * Re-exports types only from the root entry point.
+ * Use sub-paths for the actual monitor instances:
+ *
+ * - `@djangocfg/monitor/client`  — browser SDK (use in 'use client' components)
+ * - `@djangocfg/monitor/server`  — server SDK (route handlers, Server Components)
+ */
+
+export type { EventType, EventLevel, MonitorEvent } from './types'
+export type { MonitorConfig, ServerMonitorConfig } from './types'

package/src/server/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @djangocfg/monitor/server
+ *
+ * Server-side monitor for Next.js route handlers, Server Components,
+ * and middleware. Does NOT use browser APIs — safe in Node.js / Edge Runtime.
+ *
+ * @example
+ * ```ts
+ * // lib/monitor.ts
+ * import { serverMonitor } from '@djangocfg/monitor/server'
+ * serverMonitor.configure({ project: 'my-app', environment: 'production', baseUrl: 'https://api.myapp.com' })
+ * export { serverMonitor }
+ *
+ * // app/api/orders/route.ts
+ * import { serverMonitor } from '@/lib/monitor'
+ * export async function POST(req: Request) {
+ *   try { ... } catch (err) {
+ *     await serverMonitor.captureError(err, { url: req.url })
+ *     return new Response('Internal Server Error', { status: 500 })
+ *   }
+ * }
+ * ```
+ */
+
+import { monitorApi, configureMonitorApi, EventType, EventLevel } from '../_api'
+import type { FrontendEventIngestRequest } from '../_api'
+import type { ServerMonitorConfig } from '../types'
+
+export type { ServerMonitorConfig } from '../types'
+export type { EventType, EventLevel, MonitorEvent } from '../types'
+
+let _config: ServerMonitorConfig = {}
+
+async function send(events: FrontendEventIngestRequest[]): Promise<void> {
+  if (events.length === 0) return
+  try {
+    await monitorApi.monitor.ingestCreate({ events })
+  } catch {
+    // Never throw from monitor
+  }
+}
+
+function withDefaults(event: FrontendEventIngestRequest): FrontendEventIngestRequest {
+  return { project_name: _config.project, environment: _config.environment, ...event }
+}
+
+export const serverMonitor = {
+  configure(config: ServerMonitorConfig): void {
+    _config = config
+    if (config.baseUrl) configureMonitorApi(config.baseUrl)
+  },
+
+  async captureError(err: unknown, ctx?: { url?: string; extra?: Record<string, unknown> }): Promise<void> {
+    await send([withDefaults({
+      event_type: EventType.JS_ERROR,
+      level: EventLevel.ERROR,
+      message: err instanceof Error ? err.message : String(err),
+      stack_trace: err instanceof Error ? (err.stack ?? '') : '',
+      url: ctx?.url ?? '',
+      extra: ctx?.extra,
+    })])
+  },
+
+  async captureNetworkError(
+    status: number,
+    method: string,
+    apiUrl: string,
+    ctx?: { pageUrl?: string; extra?: Record<string, unknown> },
+  ): Promise<void> {
+    await send([withDefaults({
+      event_type: EventType.NETWORK_ERROR,
+      level: status >= 500 ? EventLevel.ERROR : EventLevel.WARN,
+      message: `HTTP ${status} — ${method} ${apiUrl}`,
+      url: ctx?.pageUrl ?? '',
+      http_status: status,
+      http_method: method,
+      http_url: apiUrl,
+      extra: ctx?.extra,
+    })])
+  },
+
+  async capture(event: FrontendEventIngestRequest): Promise<void> {
+    await send([withDefaults(event)])
+  },
+}