react-dashstream 0.3.1 → 0.3.2

package/skills/dashstream-event-view/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: dashstream-event-view
+description: Set up the EventView operations console and event-to-dashboard bridge
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Document `EventView` — the operations event console table component
+- Explain `EventApiConfig`, `EventFieldMapping`, and `AIOpsEvent` types
+- Cover credential resolution, severity mapping, and API polling
+- Document the event-to-dashboard bridge (`eventApiConfig` on `AIOPsDashboard`)
+
+## When to use me
+
+Use this when setting up an event console, configuring event API integration, or enabling automatic node alerts from events on the 3D dashboard.
+
+---
+
+## EventView — Operations Event Console
+
+Table component for displaying infrastructure events from a live API. Uses the same `access-key` / `access-secret-key` authentication and holographic theme as the 3D dashboard. No built-in default data — requires either `apiConfig` (to fetch from an API) or `events` (pre-fetched array).
+
+### API mode (primary usage)
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { EventView } from "react-dashstream";
+import type { EventApiConfig } from "react-dashstream";
+
+const apiConfig: EventApiConfig = {
+    baseUrl: "https://your-monitoring-server.example.com",
+    payload: { filter: {}, sortBy: "date_reception", sortOrder: "DESC" },
+    fieldMapping: {
+        id: "mc_ueid",
+        occurrence: "date_reception",
+        severityLastModified: "severity_last_modified",
+        severity: "severity",
+        owner: "owner",
+        class: "class",
+        host: "mc_host",
+        message: "msg",
+        remedySupportGroup: "ara_remedy_support_group",
+        incidentId: "ara_incident_id",
+        smsStatus: "ara_sms_status",
+        onCallNumber: "ara_on_call_number",
+        hostedApplication: "ara_hosted_application",
+        monitoringCategory: "ara_hosted_app_monitoring",
+        applicationSupportUnit: "ara_application_support_unit",
+    },
+};
+
+<EventView apiConfig={apiConfig} />
+```
+
+### How it works
+
+1. Shows credentials modal (or reuses DataProvider credentials if inside `AIOPsDashboard`)
+2. Sends `POST {baseUrl}/tsws/monitoring/api/v1.0/events/search` with the payload as JSON body
+3. Auth via headers: `access-key` and `access-secret-key`
+4. Expects response: `{ eventSeverityCount: {...}, totalCount: N, eventList: [{...}] }`
+5. Maps each object in `eventList` to `AIOpsEvent` using `fieldMapping`
+6. Maps severity strings via `severityMap` (default: `CRITICAL→Critical`, `MAJOR→Major`, `MINOR→Minor`)
+7. Polls on `refreshInterval` (default 60s)
+
+### Props
+
+| Prop | Type | Default | Notes |
+| ---- | ---- | ------- | ----- |
+| `apiConfig` | `EventApiConfig` | — | Required for API mode |
+| `events` | `AIOpsEvent[]` | — | Pre-fetched events (skips API calls) |
+| `credentials` | `Credentials` | — | Explicit creds; falls back to DataProvider → modal |
+| `columnWidthsCookie` | `string` | `"ev_col_widths"` | Cookie name for persisting column widths |
+| `title` | `string` | `"Event Console"` | Header title |
+| `theme` | `DashboardTheme` | — | Optional override; else `ThemeProvider` / default |
+
+### Features
+
+- Live API polling with configurable interval and manual refresh button
+- Configurable field mapping — any API response shape can be mapped
+- Shared auth — reuses DataProvider credentials when available
+- Severity filter chips with live counts
+- Free-text search across message, host, owner, incident ID
+- Sortable columns (click header: asc → desc → none)
+- Infinite scroll — all matching events in a single scrollable table
+- Resizable columns — drag column edges; widths persist in cookies
+- Loading spinner, error badge, last-refresh timestamp
+- Light / dark table chrome (via `ThemeProvider` or `theme` prop)
+
+---
+
+## EventApiConfig
+
+```ts
+interface EventApiConfig {
+    baseUrl: string;                        // "https://monitoring.example.com"
+    endpoint?: string;                      // default: "/tsws/monitoring/api/v1.0/events/search"
+    payload: Record<string, unknown>;       // POST body
+    fieldMapping: EventFieldMapping;        // maps API keys → AIOpsEvent keys
+    severityMap?: Record<string, EventSeverity>;  // default: { CRITICAL, MAJOR, MINOR }
+    refreshInterval?: number;               // ms, default 60000
+}
+```
+
+### EventFieldMapping
+
+Maps every `AIOpsEvent` property to the API response field name. All 15 keys required:
+
+```ts
+type EventFieldMapping = Record<keyof AIOpsEvent, string>;
+```
+
+### AIOpsEvent interface
+
+```ts
+interface AIOpsEvent {
+    id: string;
+    occurrence: string;
+    severityLastModified: string;
+    severity: "Minor" | "Major" | "Critical";
+    owner: string;
+    class: "Self-monitoring" | "SCOM" | "Situation" | "Alarm" | "Event";
+    host: string;
+    message: string;
+    remedySupportGroup: string;
+    incidentId: string;
+    smsStatus: "" | "SUCCESS" | "FAILED";
+    onCallNumber: string;
+    hostedApplication: string;
+    monitoringCategory: "24/7" | "Office Hours";
+    applicationSupportUnit: string;
+}
+```
+
+---
+
+## Credential resolution order
+
+1. `credentials` prop (if provided)
+2. `DataProvider` context credentials (when inside `AIOPsDashboard` with `liveData`)
+3. Built-in credentials modal (same UI as the 3D dashboard)
+
+---
+
+## Severity colors
+
+- **Minor** → `#ffb800` (amber)
+- **Major** → `#ff6600` (orange)
+- **Critical** → `#ff2255` (red)
+
+---
+
+## Event-to-dashboard bridge
+
+When `eventApiConfig` is passed to `AIOPsDashboard`, events are fetched in the background and nodes whose `name` (case-insensitive) matches an event `host` automatically show alert callouts.
+
+```tsx
+<AIOPsDashboard
+    eventApiConfig={eventApiConfig}
+    liveData
+    dataEndpoint="..."
+    dataBindings={dataBindings}
+    services={services}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>
+```
+
+### How it works internally
+
+1. `AIOPsDashboard` wraps children in `EventAlertsProvider` (inside `DataProvider` when `liveData` is set — shares credentials automatically)
+2. `EventAlertsProvider` fetches events using the same `fetchEvents` + `mapRawEvent` logic as `EventView`
+3. Events are grouped by **lower-cased hostname** into a `Map<string, EventHostAlert>`
+4. `ServiceNode` reads from `EventAlertsContext` via `useEventAlertsOptional()`
+5. If `componentInfo.name.toLowerCase()` matches an entry, event severity is factored into `resolveNodeSeverity` as a **third severity source** (alongside node status and metric breaches)
+6. Highest severity among all three sources wins
+7. `NodeCallout` appears automatically with the event message; multi-event hosts show `"N events – message"`
+
+### Severity mapping
+
+| Event severity | → ComponentStatus |
+| -------------- | ----------------- |
+| Critical       | `"critical"` |
+| Major          | `"warning"` |
+| Minor          | `"warning"` |
+
+**Key requirement:** Node `name` props must match event `host` values from the API (case-insensitive). Example: if the API returns `host: "SAP-PRD-APP01"`, the node must be `<ServerNode name="SAP-PRD-APP01" ... />`.
+
+### Credential resolution order (inside AIOPsDashboard)
+
+1. `DataProvider` context credentials (when `liveData` is enabled — same credentials, one login)
+2. Built-in `CredentialsModal` (when `liveData` is not enabled)
+
+**Opt-in:** Without `eventApiConfig`, no events are fetched — zero overhead.
+
+**When generating an `AIOPsDashboard` with event bridge:** Reuse the same `EventApiConfig` object that the user already has for their `EventView`. Just add it as `eventApiConfig` on `AIOPsDashboard`.
+
+---
+
+## Generating an EventApiConfig from the AI
+
+When asked to set up EventView for a new API, generate the config like this:
+
+1. Set `baseUrl` to the server's protocol + host + port
+2. Set `endpoint` only if it differs from the default `/tsws/monitoring/api/v1.0/events/search`
+3. Build `payload` based on the API's expected POST body schema
+4. Build `fieldMapping` by asking the user which API field maps to each `AIOpsEvent` property
+5. Set `severityMap` only if the API uses non-standard severity values

package/skills/dashstream-live-data/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: dashstream-live-data
+description: Wire live PromQL data into DashStream dashboards via DataProvider and bindings
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Explain the 4 data binding paths: node props, service dialog metrics, component dialog metrics, and hooks
+- Document `DataProvider`, `dataBindings`, `serviceDataBindings`, and data hooks
+- Specify the endpoint contract (method, headers, response format)
+- Show patterns for custom transforms and multi-component services
+
+## When to use me
+
+Use this when connecting a DashStream dashboard to a live Prometheus/monitoring endpoint, configuring polling, or accessing data programmatically via hooks.
+
+---
+
+## Endpoint contract
+
+| Aspect | Requirement |
+| ------ | ----------- |
+| **Method** | `GET` |
+| **URL** | `<dataEndpoint>?query=<urlEncodedQuery>` |
+| **Headers** | `access-key` and `access-secret-key` |
+| **Response** | Plain text body (trimmed). Default transform parses as number. |
+| **Errors** | Non-2xx → counted as failure per query |
+
+For JSON responses, provide a custom `dataTransform`:
+
+```tsx
+dataTransform={(raw) => {
+    const parsed = JSON.parse(String(raw));
+    return parsed?.data?.result?.[0]?.value?.[1] ?? raw;
+}}
+```
+
+---
+
+## Data path 1 — dataBindings (live props injected into service components)
+
+`dataBindings` maps **service name → prop name → PromQL query**. The dashboard polls each query, applies a transform, and injects the result as a prop on the matched child component.
+
+```ts
+type DataBinding = string | { query: string; transform?: (raw: unknown) => unknown };
+type DataBindings = Record<string, Record<string, DataBinding>>;
+```
+
+- Bare string → uses global `dataTransform` (defaults to numeric parsing)
+- Object `{ query, transform }` → uses per-binding transform
+- Service name key must match child's `name` prop **exactly**
+
+```tsx
+const dataBindings: DataBindings = {
+    "My Service": {
+        cpuLoad: 'cpu_usage{instance="srv-01"}',
+        memLoad: 'memory_usage{instance="srv-01"}',
+        status: {
+            query: 'cpu_usage{instance="srv-01"}',
+            transform: (raw) => {
+                const n = Number(raw);
+                if (n >= 85) return "critical";
+                if (n >= 70) return "warning";
+                return "online";
+            },
+        },
+        dbCapacity: 'disk_capacity{instance="db-01"}',
+        dbStatus: { query: 'disk_capacity{instance="db-01"}', transform: statusFromValue },
+    },
+};
+```
+
+### Multi-component services
+
+When a service has multiple nodes of the same type, use flat prefixed props. Each `DataBinding` maps **one prop → one query** — there is no array or object binding type.
+
+```tsx
+dataBindings={{
+    ServiceX: {
+        status: { query: 'status{instance="svcx"}', transform: statusFromValue },
+        srv1CpuLoad: 'cpu_usage{instance="srvx-01"}',
+        srv1MemLoad: 'memory_usage{instance="srvx-01"}',
+        srv1Status: { query: 'status{instance="srvx-01"}', transform: statusFromValue },
+        srv2CpuLoad: 'cpu_usage{instance="srvx-02"}',
+        srv2MemLoad: 'memory_usage{instance="srvx-02"}',
+        srv2Status: { query: 'status{instance="srvx-02"}', transform: statusFromValue },
+        dbCapacity: 'disk_capacity{instance="dbx-01"}',
+        dbStatus: { query: 'status{instance="dbx-01"}', transform: statusFromValue },
+    },
+}}
+```
+
+---
+
+## Data path 2 — serviceDataBindings (live ServiceDialog metrics)
+
+Replace static `ServiceMeta.metrics` with live-fetched values:
+
+```tsx
+serviceDataBindings={{
+    "My Service": [
+        { label: "CPU Load", query: 'cpu_usage{instance="srv-01"}', unit: "%", color: "#00e5ff" },
+        { label: "Memory", query: 'memory_usage{instance="srv-01"}', unit: "%", color: "#bb55ff" },
+        { label: "Disk", query: 'disk_capacity{instance="db-01"}', unit: "%", color: "#ff8c00" },
+    ],
+}}
+```
+
+```ts
+interface ServiceMetricBinding {
+    label: string;       // Row label
+    query: string;       // PromQL query
+    unit?: string;       // Suffix (e.g. "%", "ms")
+    color?: string;      // Accent color
+    transform?: (raw: unknown) => string;  // Custom formatter
+}
+```
+
+When provided, live values **replace** static `ServiceMeta.metrics` for that service.
+
+---
+
+## Data path 3 — live component dialog metrics
+
+To feed live query values into custom gauges, expose each metric as a prop on your service component. Use `dataBindings` to inject them. Then build the `dialogMetrics` array from those props:
+
+```tsx
+function MyService({ name, status = "online", cpuLoad = 42, memLoad = 60, iops = 20 }: any) {
+    return (
+        <Service name={name} status={status} connections={[/* ... */]}>
+            <ServerNode
+                name="SRV-01"
+                status={status}
+                cpuLoad={cpuLoad}
+                memLoad={memLoad}
+                ex={200} ey={380}
+                compactOffset={{ x: -30, y: -20 }}
+                zIndex={8}
+                dialogMetrics={[
+                    { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: cpuLoad },
+                    { id: "mem", label: "MEMORY", sublabel: "HEAP", value: memLoad },
+                    { id: "iops", label: "IOPS", sublabel: "DISK OPS", value: iops, icon: "disk", warnAt: 50, critAt: 80 },
+                ]}
+            />
+        </Service>
+    );
+}
+
+<AIOPsDashboard
+    liveData
+    dataEndpoint="..."
+    dataBindings={{
+        "My Service": {
+            cpuLoad: 'cpu_usage{instance="srv-01"}',
+            memLoad: 'memory_usage{instance="srv-01"}',
+            iops: 'disk_iops{instance="srv-01"}',
+            status: { query: 'cpu_usage{instance="srv-01"}', transform: statusFromValue },
+        },
+    }}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>
+```
+
+The dashboard injects `cpuLoad`, `memLoad`, `iops` as live props → they flow into `dialogMetrics` → gauges update automatically on every poll.
+
+---
+
+## Data path 4 — data hooks (programmatic access)
+
+Access live data context anywhere inside the dashboard:
+
+```tsx
+import { useAIOpsData, useAIOpsDataOptional, useQueryResult } from "react-dashstream";
+
+function CustomWidget() {
+    const { data, isRefreshing, lastRefreshError, lastRefreshTime, credentialsSet } = useAIOpsData();
+    const cpu = useQueryResult('cpu_usage{instance="srv-01"}');
+    return <div>CPU: {String(cpu)}</div>;
+}
+```
+
+| Hook | Returns | Throws? |
+| ---- | ------- | ------- |
+| `useAIOpsData()` | `DataContextValue` | Yes — outside `DataProvider` |
+| `useAIOpsDataOptional()` | `DataContextValue \| null` | No |
+| `useQueryResult(query)` | `unknown \| null` | Yes — outside `DataProvider` |
+
+```ts
+interface DataContextValue {
+    data: Record<string, unknown>;   // Raw responses keyed by query
+    isRefreshing: boolean;
+    lastRefreshError: string | null;
+    lastRefreshTime: Date | null;
+    credentialsSet: boolean;
+    setCredentials: (creds: Credentials) => void;
+}
+```
+
+---
+
+## Standalone DataProvider
+
+Use the data layer without `AIOPsDashboard`:
+
+```tsx
+import { DataProvider, useAIOpsData } from "react-dashstream";
+
+<DataProvider
+    config={{
+        endpoint: "https://prometheus.example.com/api/v1/query",
+        queries: ['cpu_usage{instance="srv-01"}'],
+        refreshInterval: 15000,
+    }}
+>
+    <MyContent />
+</DataProvider>
+```
+
+---
+
+## Full live-data dashboard example
+
+```tsx
+<AIOPsDashboard
+    brandName="LIVE MONITOR"
+    services={services}
+    liveData={true}
+    dataEndpoint="https://prometheus.example.com/api/v1/query"
+    dataRefreshInterval={10000}
+    dataBindings={{
+        "My Service": {
+            cpuLoad: 'cpu_usage{instance="srv-01"}',
+            status: { query: 'cpu_usage{instance="srv-01"}', transform: statusFromValue },
+        },
+    }}
+    serviceDataBindings={{
+        "My Service": [
+            { label: "CPU", query: 'cpu_usage{instance="srv-01"}', unit: "%", color: "#00e5ff" },
+        ],
+    }}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>
+```