@djangocfg/monitor 2.1.216 → 2.1.218

package/README.md

@@ -1,8 +1,6 @@
 # @djangocfg/monitor
 
-Browser error and event monitoring SDK for django-cfg backends.
-
-**Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
+Browser + server error monitoring SDK for [DjangoCFG](https://djangocfg.com) backends.
 
 ## Install
 
@@ -10,112 +8,27 @@ Browser error and event monitoring SDK for django-cfg backends.
 pnpm add @djangocfg/monitor
 ```
 
-## What's Inside
-
-- **JS Error Capture** — `window.onerror` + `unhandledrejection` with SHA-256 fingerprinting
-- **Console Capture** — intercepts `console.warn` / `console.error` (consola reporter or native patch)
-- **Network Monitoring** — `monitoredFetch` wrapper reports non-2xx responses
-- **Zod Validation Errors** — listens to `zod-validation-error` custom events (auto-integrates with `@djangocfg/api`)
-- **Session Tracking** — anonymous `fm_session_id` UUID in localStorage + cookie
-- **Server-side Capture** — Node.js / Edge Runtime safe, no browser APIs
-- **Auto-flush** — batched delivery via generated API client; `KeepAliveFetchAdapter` survives page unload
-- **Type-safe** — types generated from Django OpenAPI schema via `make gen`
-
 ## Entry Points
 
-| Entry | Import | Description |
-|-------|--------|-------------|
-| **Main** | `@djangocfg/monitor` | Types only, server-safe |
-| **Client** | `@djangocfg/monitor/client` | Browser SDK (`"use client"`) |
-| **Server** | `@djangocfg/monitor/server` | Node.js / Edge Runtime |
-
-## Package Structure
-
-```
-src/
-├── _api/
-│   ├── BaseClient.ts              # monitorApi singleton (MemoryStorageAdapter)
-│   ├── index.ts                   # Re-exports types, enums, monitorApi
-│   └── generated/
-│       └── cfg_monitor/  # Auto-generated — do not edit
-│           ├── http.ts            # FetchAdapter, KeepAliveFetchAdapter
-│           └── ...
-├── types/
-│   ├── events.ts                  # EventType, EventLevel, MonitorEvent
-│   └── config.ts                  # MonitorConfig, ServerMonitorConfig
-├── client/
-│   ├── index.ts                   # FrontendMonitor, monitoredFetch, getSessionId
-│   ├── capture/
-│   │   ├── js-errors.ts           # window.onerror + unhandledrejection
-│   │   ├── console.ts             # consola reporter / console.* patch
-│   │   ├── network.ts             # monitoredFetch wrapper
-│   │   ├── validation.ts          # zod-validation-error CustomEvent listener
-│   │   ├── session.ts             # UUID session management
-│   │   └── fingerprint.ts         # SHA-256 deduplication fingerprint
-│   ├── store/
-│   │   └── index.ts               # zustand vanilla event buffer
-│   └── transport/
-│       └── ingest.ts              # sendBatch via monitorApi / KeepAliveFetchAdapter
-├── server/
-│   └── index.ts                   # serverMonitor singleton
-└── index.ts                       # Types-only re-export
-```
+| Entry | Use |
+|-------|-----|
+| `@djangocfg/monitor` | Types only — server-safe |
+| `@djangocfg/monitor/client` | Browser SDK (`'use client'`) |
+| `@djangocfg/monitor/server` | Node.js / Edge Runtime |
 
-## How It Works
+## Client (React / Next.js)
 
-All transport uses the **generated API client** (`monitorApi`) — no hardcoded URLs or raw `fetch` calls.
-
-- **Normal flush** → `monitorApi.monitor.ingestCreate(batch)` (standard `FetchAdapter`)
-- **Page unload flush** → separate `monitorApiBeacon` instance with `KeepAliveFetchAdapter` — sets `keepalive: true` on every request, so the browser completes delivery even after navigation
-
-**Automatic error collection** (no extra setup after `FrontendMonitor.init()`):
-
-| Source | Mechanism |
-|--------|-----------|
-| JS exceptions | `window.onerror` + `unhandledrejection` |
-| Console warnings/errors | consola reporter or `console.*` patch |
-| `@djangocfg/api` Zod failures | `zod-validation-error` CustomEvent |
-| Network errors | `monitoredFetch` wrapper |
-| Server exceptions | `serverMonitor.captureError()` |
-
-## Client Usage (React / Next.js)
-
-### MonitorProvider
-
-```tsx
-// components/MonitorProvider.tsx
-'use client'
-
-import { useEffect } from 'react'
-import { FrontendMonitor } from '@djangocfg/monitor/client'
-
-export function MonitorProvider() {
-  useEffect(() => {
-    FrontendMonitor.init({
-      project: process.env.NEXT_PUBLIC_PROJECT_NAME ?? 'my-app',
-      environment: process.env.NODE_ENV,
-      // baseUrl: 'https://api.myapp.com',  // default: same origin
-      // flushInterval: 5000,               // default: 5s
-      // captureJsErrors: true,             // default: true
-      // captureConsole: true,              // default: true
-      // debug: false,
-    })
-    return () => FrontendMonitor.destroy()
-  }, [])
-
-  return null
-}
-```
+Drop `MonitorProvider` into your root layout — that's all:
 
 ```tsx
 // app/layout.tsx
-import { MonitorProvider } from '@/components/MonitorProvider'
+import { MonitorProvider } from '@djangocfg/monitor/client'
 
 export default function RootLayout({ children }) {
   return (
-    <html lang="en">
+    <html>
       <body>
-        <MonitorProvider />
+        <MonitorProvider project="my-app" environment={process.env.NODE_ENV} />
         {children}
       </body>
     </html>
@@ -123,18 +36,18 @@ export default function RootLayout({ children }) {
 }
 ```
 
-### Network Monitoring
+`MonitorProvider` initialises `FrontendMonitor` on mount and tears it down on unmount.
 
-```typescript
-import { monitoredFetch } from '@djangocfg/monitor/client'
+**What gets captured automatically** (no extra setup):
 
-const response = await monitoredFetch('/api/orders', {
-  method: 'POST',
-  body: JSON.stringify(order),
-})
-```
+| Source | Mechanism |
+|--------|-----------|
+| JS exceptions | `window.onerror` + `unhandledrejection` |
+| Console warnings/errors | consola reporter or `console.*` patch |
+| `@djangocfg/api` Zod failures | `zod-validation-error` CustomEvent |
+| Network errors | `monitoredFetch` wrapper |
 
-### Manual Event Capture
+### Manual capture
 
 ```typescript
 import { FrontendMonitor } from '@djangocfg/monitor/client'
@@ -149,40 +62,41 @@ FrontendMonitor.capture({
 })
 ```
 
-### Session ID
+### Network wrapper
 
 ```typescript
-import { getSessionId } from '@djangocfg/monitor/client'
+import { monitoredFetch } from '@djangocfg/monitor/client'
 
-const sessionId = getSessionId() // UUID stored in localStorage + cookie
+const res = await monitoredFetch('/api/orders', { method: 'POST', body: JSON.stringify(order) })
 ```
 
-## Server Usage (Next.js Route Handlers / Server Components)
+### Config options
 
-### Configure once
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `project` | `string` | `''` | Project name sent with every event |
+| `environment` | `string` | `''` | `production` / `staging` / `development` |
+| `baseUrl` | `string` | same origin | Base URL of the django-cfg backend |
+| `flushInterval` | `number` | `5000` | Buffer flush interval (ms) |
+| `maxBufferSize` | `number` | `20` | Max events before immediate flush |
+| `captureJsErrors` | `boolean` | `true` | Capture `window.onerror` + unhandled rejections |
+| `captureConsole` | `boolean` | `true` | Intercept `console.warn` / `console.error` |
+| `debug` | `boolean` | `false` | Log init info to console |
+
+## Server (Next.js Route Handlers)
 
 ```typescript
 // lib/monitor.ts
 import { serverMonitor } from '@djangocfg/monitor/server'
-
-serverMonitor.configure({
-  project: process.env.PROJECT_NAME ?? 'my-app',
-  environment: process.env.NODE_ENV,
-  // baseUrl: 'https://api.myapp.com',  // required if backend is on different origin
-})
-
+serverMonitor.configure({ project: 'my-app', environment: process.env.NODE_ENV })
 export { serverMonitor }
-```
 
-### Route Handler
-
-```typescript
 // app/api/orders/route.ts
 import { serverMonitor } from '@/lib/monitor'
 
 export async function POST(req: Request) {
   try {
-    // ... handle request
+    // ...
   } catch (err) {
     await serverMonitor.captureError(err, { url: req.url })
     return new Response('Internal Server Error', { status: 500 })
@@ -190,152 +104,60 @@ export async function POST(req: Request) {
 }
 ```
 
-### Network Error
-
-```typescript
-const response = await fetch(upstreamUrl)
-if (!response.ok) {
-  await serverMonitor.captureNetworkError(
-    response.status,
-    'GET',
-    upstreamUrl,
-    { pageUrl: req.url },
-  )
-}
-```
-
-### Arbitrary Event
-
-```typescript
-import { EventType, EventLevel } from '@djangocfg/monitor/server'
-
-await serverMonitor.capture({
-  event_type: EventType.WARNING,
-  level: EventLevel.WARN,
-  message: 'Rate limit approaching',
-  url: req.url,
-  extra: { remaining: 5 },
-})
-```
-
-## Types
-
-```typescript
-import type { MonitorConfig, MonitorEvent } from '@djangocfg/monitor'
-import { EventType, EventLevel } from '@djangocfg/monitor'
-
-EventType.JS_ERROR      // 'js_error'
-EventType.NETWORK_ERROR // 'network_error'
-EventType.WARNING       // 'warning'
-EventType.ERROR         // 'error'
-EventType.INFO          // 'info'
-
-EventLevel.ERROR        // 'error'
-EventLevel.WARN         // 'warn'
-EventLevel.INFO         // 'info'
-```
-
-### MonitorConfig
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `project` | `string` | `''` | Project name sent with every event |
-| `environment` | `string` | `''` | `production` / `staging` / `development` |
-| `baseUrl` | `string` | `''` | Base URL of the django-cfg backend (same origin by default) |
-| `flushInterval` | `number` | `5000` | Buffer flush interval (ms) |
-| `maxBufferSize` | `number` | `20` | Max events before immediate flush |
-| `captureJsErrors` | `boolean` | `true` | Capture `window.onerror` + unhandled rejections |
-| `captureConsole` | `boolean` | `true` | Intercept `console.warn` / `console.error` |
-| `debug` | `boolean` | `false` | Log init info to console |
-
-### ServerMonitorConfig
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `project` | `string` | `''` | Project name |
-| `environment` | `string` | `''` | Environment name |
-| `baseUrl` | `string` | `''` | Base URL of the django-cfg backend (absolute required on server) |
-
-## Zod Validation Integration
-
-`@djangocfg/api` automatically dispatches a `zod-validation-error` CustomEvent whenever a response fails schema validation. `@djangocfg/monitor/client` listens and forwards it as a `WARNING` — zero setup needed.
-
-```
-@djangocfg/api fetcher validates response with Zod
-    → dispatches window CustomEvent('zod-validation-error', { detail })
-        → @djangocfg/monitor/client capture/validation.ts catches it
-            → pushed to store → flushed to backend
-```
-
-## Custom HTTP Adapter
-
-The generated `KeepAliveFetchAdapter` is also available if you need it elsewhere:
+Or use the `withMonitor` HOC from `@djangocfg/nextjs/monitor`:
 
 ```typescript
-import { KeepAliveFetchAdapter } from '@djangocfg/monitor/client'
-// or directly from generated:
-import { API, KeepAliveFetchAdapter } from '@djangocfg/monitor/client'
+import { withMonitor } from '@djangocfg/nextjs/monitor'
 
-const api = new API('https://api.myapp.com', {
-  httpClient: new KeepAliveFetchAdapter(),
+export const POST = withMonitor(async (req) => {
+  // errors are captured automatically
 })
 ```
 
 ## Django Backend
 
-Enable the `cfg_monitor` extension:
-
 ```python
 # cfg.py
-from django_cfg import DjangoConfig
-
 class Config(DjangoConfig):
-    installed_apps = [
-        ...
-        'django_cfg.apps.system.monitor',
-    ]
+    installed_apps = [..., 'django_cfg.apps.system.monitor']
 ```
 
-| | |
-|---|---|
-| Endpoint | `POST /cfg/monitor/ingest/` |
-| Auth | not required |
-| Rate limit | 100 req/min per IP |
-| Batch size | up to 50 events |
+Ingest endpoint: `POST /cfg/monitor/ingest/` — no auth required, 100 req/min per IP.
 
-## Development
+## Browser Console Testing
 
-```bash
-# Regenerate API client from Django OpenAPI schema
-make generate
+After `MonitorProvider` mounts, `window.monitor` is available in DevTools for manual testing:
 
-# Build package
-make build
+```javascript
+// Fire events from DevTools console
+window.monitor.error('Payment failed', { orderId: '123' })
+window.monitor.warn('Slow response', { ms: 2400 })
+window.monitor.info('User action', { action: 'checkout' })
+window.monitor.network(404, 'GET', '/api/users/')
+window.monitor.network(502, 'POST', '/api/orders/', { retries: 3 })
 
-# Watch mode
-pnpm dev
+// Force-send buffered events immediately
+window.monitor.flush()
 
-# Type check
-pnpm check
+// Inspect current state
+window.monitor.status()
+// → logs config, buffer size, session_id
 ```
 
-## Peer Dependencies
+## Debug Panel Integration
 
-| Package | Required | Description |
-|---------|----------|-------------|
-| `consola` | optional | Uses consola reporter instead of patching `console.*` |
-| `zustand` | optional | Required for the client entry point event buffer |
+Install `@djangocfg/debuger` alongside this package — it auto-bridges the monitor event store into the debug panel's Logs tab. No extra setup needed.
 
-## Requirements
+```bash
+pnpm add @djangocfg/debuger
+```
 
-- Next.js >= 15 (or any React >= 19 app)
-- Django with `django_cfg >= 1.7` and `monitor` extension
+Events captured by monitor (JS errors, console, network) appear in the panel as `monitor:JS_ERROR`, `monitor:NETWORK_ERROR`, etc.
 
-## License
+## Safety
 
-MIT
+Transport errors are **always swallowed** — monitor never crashes your app and never sends its own errors to itself. If the backend is unreachable, events are silently dropped.
 
-## Links
+## License
 
-- [DjangoCFG Documentation](https://djangocfg.com)
-- [GitHub](https://github.com/markolofsen/django-cfg)
+MIT