@djangocfg/monitor 2.1.216

package/README.md

@@ -0,0 +1,341 @@
+# @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.
+
+## Install
+
+```bash
+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
+```
+
+## How It Works
+
+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
+}
+```
+
+```tsx
+// app/layout.tsx
+import { MonitorProvider } from '@/components/MonitorProvider'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <MonitorProvider />
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+
+### Network Monitoring
+
+```typescript
+import { monitoredFetch } from '@djangocfg/monitor/client'
+
+const response = await monitoredFetch('/api/orders', {
+  method: 'POST',
+  body: JSON.stringify(order),
+})
+```
+
+### Manual Event Capture
+
+```typescript
+import { FrontendMonitor } from '@djangocfg/monitor/client'
+import { EventType, EventLevel } from '@djangocfg/monitor'
+
+FrontendMonitor.capture({
+  event_type: EventType.JS_ERROR,
+  level: EventLevel.ERROR,
+  message: 'Payment failed',
+  url: window.location.href,
+  extra: { orderId: '123' },
+})
+```
+
+### Session ID
+
+```typescript
+import { getSessionId } from '@djangocfg/monitor/client'
+
+const sessionId = getSessionId() // UUID stored in localStorage + cookie
+```
+
+## Server Usage (Next.js Route Handlers / Server Components)
+
+### Configure once
+
+```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
+})
+
+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 })
+  }
+}
+```
+
+### 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:
+
+```typescript
+import { KeepAliveFetchAdapter } from '@djangocfg/monitor/client'
+// or directly from generated:
+import { API, KeepAliveFetchAdapter } from '@djangocfg/monitor/client'
+
+const api = new API('https://api.myapp.com', {
+  httpClient: new KeepAliveFetchAdapter(),
+})
+```
+
+## 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',
+    ]
+```
+
+| | |
+|---|---|
+| Endpoint | `POST /cfg/monitor/ingest/` |
+| Auth | not required |
+| Rate limit | 100 req/min per IP |
+| Batch size | up to 50 events |
+
+## Development
+
+```bash
+# Regenerate API client from Django OpenAPI schema
+make generate
+
+# Build package
+make build
+
+# Watch mode
+pnpm dev
+
+# Type check
+pnpm check
+```
+
+## Peer Dependencies
+
+| Package | Required | Description |
+|---------|----------|-------------|
+| `consola` | optional | Uses consola reporter instead of patching `console.*` |
+| `zustand` | optional | Required for the client entry point event buffer |
+
+## Requirements
+
+- Next.js >= 15 (or any React >= 19 app)
+- Django with `django_cfg >= 1.7` and `monitor` extension
+
+## License
+
+MIT
+
+## Links
+
+- [DjangoCFG Documentation](https://djangocfg.com)
+- [GitHub](https://github.com/markolofsen/django-cfg)