react-dashstream 0.3.1 → 0.3.3

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

@@ -0,0 +1,198 @@
+---
+name: dashstream-datacenter-view
+description: Build topology maps with DatacenterView, buildings, geography, and drill-down
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Document `DatacenterView` — SVG topology or geographic map with CSS 3D building markers
+- Explain both array config and declarative JSX composition APIs
+- Cover sites, building variants, connections, metric bindings, and geography
+- Show how drill-down integrates with `AIOPsDashboard`
+
+## When to use me
+
+Use this when building a datacenter topology map, geographic view, or configuring building markers with drill-down dashboards.
+
+---
+
+## Overview
+
+SVG-based **network topology** (grid) or optional **geographic outline** (consumer-supplied SVG path `d`), CSS **3D building** markers, animated links, and **drill-down** into a nested `AIOPsDashboard` when the user selects a site or building.
+
+---
+
+## Data model
+
+- **`DatacenterBuildingConfig`** — one marker on the map (`id`, `name`, `subtitle`, `x` / `y` as **percent** of the 800×600 scene, `status`, `metrics`, `services`, `renderServices`, `variant`, optional `brand`, `isExternal`).
+- **`siteId`** — optional; multiple buildings with the same `siteId` share **one marker**, **combined metrics** (sums / averages for PUE, temperature, uptime), and a **multi-building cluster** visualization (each building's `variant` is shown). Optional **`siteLabels`** (`Record<string, { label: string; subtitle?: string }>`) overrides auto-generated titles. **`DatacenterSite`** can supply `label` / `subtitle` per `siteId`; the **`siteLabels`** prop merges on top (prop wins on conflict).
+
+---
+
+## Minimal usage (array config)
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { DatacenterView } from "react-dashstream";
+import type { DatacenterBuildingConfig, DatacenterConnection } from "react-dashstream";
+
+const dataCenters: DatacenterBuildingConfig[] = [
+    /* id, x, y (%), metrics, services, renderServices, variant, siteId? … */
+];
+const connections: DatacenterConnection[] = [];
+
+<DatacenterView dataCenters={dataCenters} connections={connections} />
+```
+
+---
+
+## Declarative JSX topology
+
+Instead of a `dataCenters` array, pass `children` using `DatacenterSite` and shape components:
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { DatacenterView, DatacenterSite, TowerDC, FlatDC } from "react-dashstream";
+
+<DatacenterView connections={[]}>
+    <DatacenterSite siteId="riyadh-hub" x={42} y={38} label="Riyadh hub" subtitle="Primary region">
+        <TowerDC
+            id="dc-east-1"
+            name="East tower"
+            subtitle="Tier III"
+            status="online"
+            metrics={{
+                carbonEmissions: 0,
+                powerUtilization: 0,
+                cooling: 0,
+                pue: 1.4,
+                uptime: 99.9,
+                activeServers: 0,
+                temperature: 22,
+                networkThroughput: 0,
+            }}
+            services={[]}
+        >
+            {/* Service / ServerNode / … drill-down tree */}
+        </TowerDC>
+        <FlatDC
+            id="dc-flat-2"
+            name="Flat block"
+            subtitle="Storage"
+            status="online"
+            metrics={{
+                carbonEmissions: 0,
+                powerUtilization: 0,
+                cooling: 0,
+                pue: 1.3,
+                uptime: 99.5,
+                activeServers: 0,
+                temperature: 21,
+                networkThroughput: 0,
+            }}
+            services={[]}
+        />
+    </DatacenterSite>
+</DatacenterView>
+```
+
+**Available building shapes:** `StandardDC`, `TowerDC`, `FlatDC`, `StorageDC`, `GoogleDC`, `MicroDC`, `OfficeDC` (alias of `MicroDC`). Use `Datacenter` with `variant` for a single generic component.
+
+Building components render `null` on the map; `children` on each building are the drill-down `Service` tree (same as `renderServices()` in the array API).
+
+`collectDatacenterTree(children)` is available if you need the resolved `DatacenterBuildingConfig[]` outside the view.
+
+---
+
+## Connections
+
+```ts
+interface DatacenterConnection {
+    from: string;          // Building id or siteId
+    to: string;            // Building id or siteId
+    throughput: string;    // Label (e.g. "10 Gbps")
+    isExternal?: boolean;  // External link styling
+}
+```
+
+---
+
+## DatacenterMetrics
+
+```ts
+interface DatacenterMetrics {
+    carbonEmissions: number;
+    powerUtilization: number;
+    cooling: number;
+    pue: number;
+    uptime: number;
+    activeServers: number;
+    temperature: number;
+    networkThroughput: number;
+}
+```
+
+Used on markers and for site-level aggregation.
+
+---
+
+## Mock metrics
+
+Pass `dataCenters` with embedded `metrics`. No `DataProvider` required.
+
+---
+
+## PromQL (live) metrics on markers
+
+1. Wrap the tree in **`DataProvider`** with `config.queries` including every query used by `metricBindings`, collected via `extractDatacenterMetricQueries(metricBindings)` (and merge with queries for any nested `AIOPsDashboard` if you use `aiOpsDashboardProps`).
+2. Pass **`metricBindings`**: `Record<buildingId, Partial<Record<keyof DatacenterMetrics, DataBinding>>>` — same `DataBinding` shape as service-level bindings (`string` or `{ query, transform? }`).
+3. `DatacenterView` calls `useAIOpsDataOptional()` and merges transformed numbers over each building's static `metrics` (site-level rows aggregate the merged per-building values).
+
+This path is **independent** of `AIOPsDashboard`'s `dataBindings` (which key off service `name` on carousel children).
+
+---
+
+## Drill-down dashboard
+
+`aiOpsDashboardProps` is spread onto the inner `AIOPsDashboard`; `services`, `theme`, `children` (from `renderServices()`), and branding are forced from the selected building so the map stays consistent. Use `aiOpsDashboardProps` for `liveData`, `dataEndpoint`, `dataBindings`, `serviceDataBindings`, etc., for service-level PromQL inside the opened datacenter.
+
+---
+
+## Geography (optional)
+
+`showGeography` and `geography: { outlinePathD, referencePoints? }` — the package does **not** ship country assets; the app parses or provides an SVG path `d` string (see `example/SaudiMapView.tsx`).
+
+---
+
+## DatacenterViewProps (full reference)
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `children` | `ReactNode` | — | Declarative topology (`DatacenterSite`, `TowerDC`, …). When set, `dataCenters` is ignored (dev warning if both are passed) |
+| `dataCenters` | `DatacenterBuildingConfig[]` | `[]` | Flat / JSON-friendly config; required unless `children` is used |
+| `connections` | `DatacenterConnection[]` | `[]` | Link lines between building or site ids |
+| `metricBindings` | `DatacenterMetricBindings` | — | Building id → metric field → PromQL `DataBinding`; needs `DataProvider` + `extractDatacenterMetricQueries` |
+| `dataTransform` | `(raw: unknown) => unknown` | `defaultDataTransform` | Applied to each binding unless overridden per binding |
+| `geography` | `DatacenterGeography` | — | `outlinePathD` + optional `referencePoints` (SVG coords) |
+| `showGeography` | `boolean` | `false` | When true, draws outline + reference points |
+| `mapTitle` | `string` | `"Geography — Operations"` | Header when `showGeography` |
+| `topologyTitle` | `string` | `"Network topology"` | Header when not showing geography |
+| `topologyAffiliatesLabel` | `string` | `"AFFILIATES"` | Label in topology-only mode (affiliates zone) |
+| `brandText` | `string` | `"AIOps"` | Header brand |
+| `headerTag` | `string` | `"COMMAND CENTER"` | Corner tag |
+| `initialBuildingId` | `string` | — | Building id to open when `openDashboardOnMount` is true |
+| `openDashboardOnMount` | `boolean` | `false` | Auto-zoom into `initialBuildingId` |
+| `onNavigateEvents` | `() => void` | — | e.g. switch app view to event console |
+| `theme` | `DashboardTheme` | — | Passed through to drill-down dashboard |
+| `onThemeChange` | `(t) => void` | — | |
+| `backgroundImage` / `lightBackgroundImage` | `string` | — | Drill-down `AIOPsDashboard` backgrounds |
+| `aiOpsDashboardProps` | `Partial<AIOPsDashboardProps>` | — | Spread first; `services`, children, theme, branding overridden from selection |
+| `defaultBuildingBrand` | `string` | `"AIOps"` | Fallback label on 3D building faces |
+| `siteLabels` | `Record<string, DatacenterSiteLabels>` | — | Per-siteId titles for multi-building markers |
+| `showMapScaleControls` | `boolean` | `true` | Size / hover sliders in header (map mode) |
+| `mapFooter` | `ReactNode` | — | Rendered below the map when drill-down is not active |

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>
+```