@stackwright-pro/pulse 0.1.0

package/README.md

@@ -0,0 +1,348 @@
+# @stackwright-pro/pulse
+
+> Source-agnostic real-time data polling for Stackwright Pro. Works with OpenAPI, WebSockets, GraphQL, SSE, or any data source.
+
+[![License: PROPRIETARY](https://img.shields.io/badge/License-PROPRIETARY-red.svg)](./package.json)
+
+## Features
+
+- **🔌 Source-Agnostic** - Works with ANY async data source via a simple `fetcher` interface
+- **⏱️ Real-time Polling** - Configurable polling intervals with automatic retries
+- **📊 State Management** - Built-in states: `loading`, `live`, `stale`, `error`
+- **🛡️ Runtime Validation** - Optional Zod schema validation for data integrity
+- **⚡ React Query Powered** - Leverages TanStack Query for caching and background updates
+- **🎨 Flexible UI** - Render props with metadata for custom state indicators
+
+## Installation
+
+```bash
+pnpm add @stackwright-pro/pulse
+```
+
+**Peer Dependencies:**
+```bash
+pnpm add react react-dom @tanstack/react-query
+```
+
+## Quick Start
+
+### Basic Usage
+
+```tsx
+import { Pulse, PulseIndicator } from '@stackwright-pro/pulse';
+
+function EquipmentPanel() {
+  return (
+    <Pulse
+      fetcher={() => fetch('/api/equipment').then(r => r.json())}
+      interval={5000}
+    >
+      {(equipment, meta) => (
+        <>
+          <PulseIndicator meta={meta} />
+          <EquipmentGrid data={equipment} />
+        </>
+      )}
+    </Pulse>
+  );
+}
+```
+
+### With Zod Validation
+
+```tsx
+import { z } from 'zod';
+import { Pulse } from '@stackwright-pro/pulse';
+
+const EquipmentSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: z.enum(['online', 'offline', 'maintenance']),
+  lastUpdated: z.string().datetime(),
+});
+
+function EquipmentPanel() {
+  return (
+    <Pulse
+      fetcher={() => fetch('/api/equipment').then(r => r.json())}
+      schema={EquipmentSchema}
+      interval={5000}
+    >
+      {(equipment) => <EquipmentGrid data={equipment} />}
+    </Pulse>
+  );
+}
+```
+
+### Custom State UI
+
+```tsx
+import { Pulse } from '@stackwright-pro/pulse';
+
+function CustomEquipmentPanel() {
+  return (
+    <Pulse
+      fetcher={fetchEquipment}
+      interval={5000}
+      staleThreshold={30000}
+      maxStaleAge={60000}
+      loadingState={<SkeletonLoader />}
+      errorState={(meta) => (
+        <ErrorBanner 
+          message="Failed to load equipment" 
+          lastUpdated={meta.lastUpdated}
+          onRetry={meta.refetch}
+        />
+      )}
+      emptyState={<EmptyState message="No equipment found" />}
+    >
+      {(equipment, meta) => (
+        <>
+          {meta.state === 'stale' && <StaleBanner />}
+          <EquipmentGrid data={equipment} />
+        </>
+      )}
+    </Pulse>
+  );
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      <Pulse> Component                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   ┌─────────────┐    ┌──────────────┐    ┌───────────────┐  │
+│   │  Render     │    │   usePulse   │    │ React Query  │  │
+│   │  Props      │───▶│    Hook      │───▶│   Provider    │  │
+│   └─────────────┘    └──────────────┘    └───────────────┘  │
+│         │                   │                     │          │
+│         │                   │                     │          │
+│         ▼                   ▼                     ▼          │
+│   ┌─────────────┐    ┌──────────────┐    ┌───────────────┐  │
+│   │ PulseMeta   │    │   Fetcher    │    │   Caching &   │  │
+│   │ (metadata)  │    │  Validation  │    │   Polling     │  │
+│   └─────────────┘    └──────────────┘    └───────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+              ┌───────────────────────────────────┐
+              │      ANY Data Source              │
+              ├───────────────────────────────────┤
+              │ • OpenAPI (fetch/axios)           │
+              │ • WebSocket                       │
+              │ • GraphQL (urql/Apollo)           │
+              │ • SSE (EventSource)               │
+              │ • Custom async functions          │
+              └───────────────────────────────────┘
+```
+
+## API Reference
+
+### `<Pulse>` Component
+
+```tsx
+interface PulseProps<T> {
+  // Core
+  fetcher: () => Promise<T>;           // Your data fetching function
+  children: (data: T, meta: PulseMeta) => React.ReactNode;
+  
+  // Polling config
+  interval?: number;                   // Poll interval in ms (default: 5000, min: 1000)
+  enabled?: boolean;                   // Enable/disable polling (default: true)
+  retryCount?: number;                 // Number of retries on error (default: 3)
+  refetchOnWindowFocus?: boolean;      // Refetch on window focus (default: true)
+  
+  // State thresholds (in milliseconds)
+  staleThreshold?: number;             // Show stale warning (default: 30000)
+  maxStaleAge?: number;                // Show error state (default: 60000)
+  
+  // Validation
+  schema?: ZodSchema<T>;               // Optional Zod schema
+  
+  // Custom state UI
+  loadingState?: React.ReactNode;
+  errorState?: React.ReactNode | ((meta: PulseMeta) => React.ReactNode);
+  emptyState?: React.ReactNode;
+  showStaleDataOnError?: boolean;       // Show data during error (default: true)
+}
+```
+
+### `PulseMeta` (passed to children)
+
+```tsx
+interface PulseMeta {
+  lastUpdated: Date;        // Timestamp of last successful fetch
+  isStale: boolean;         // Data older than staleThreshold
+  isError: boolean;        // Data older than maxStaleAge or fetch failed
+  isLoading: boolean;      // Currently fetching
+  errorCount: number;      // Number of consecutive errors
+  refetch: () => void;     // Manual refresh trigger
+  state: 'loading' | 'live' | 'stale' | 'error';
+}
+```
+
+### `<PulseIndicator>` Component
+
+```tsx
+interface PulseIndicatorProps {
+  meta: PulseMeta;                              // Required meta object
+  showSeconds?: boolean;                       // Show "Xs ago" (default: true)
+  className?: string;                           // Additional CSS classes
+  labels?: {
+    live?: string;                              // Custom live label
+    syncing?: string;                           // Custom syncing label
+    stale?: string;                             // Custom stale label
+    error?: string;                             // Custom error label
+  };
+}
+```
+
+### `usePulse` Hook
+
+```tsx
+const result = usePulse<T>({
+  fetcher,
+  interval = 5000,
+  staleThreshold = 30000,
+  maxStaleAge = 60000,
+  schema,
+  enabled = true,
+  refetchOnWindowFocus = true,
+  retryCount = 3,
+});
+
+// Returns
+{
+  data: T | undefined,
+  meta: PulseMeta,
+  state: PulseState,
+  error: Error | null,
+}
+```
+
+## Source Adapters
+
+The `fetcher` prop accepts **any** async function. This makes Pulse work with:
+
+| Source | Example Fetcher |
+|--------|-----------------|
+| REST/OpenAPI | `() => fetch('/api/data').then(r => r.json())` |
+| WebSocket | `() => websocket.nextMessage()` |
+| GraphQL | `() => client.query({ query: MY_QUERY })` |
+| SSE | `() => eventSource.nextEvent()` |
+
+See [SOURCE_ADAPTERS.md](./docs/SOURCE_ADAPTERS.md) for planned first-party adapter documentation.
+
+## State Transitions
+
+```
+┌──────────┐
+│ loading  │ ← Initial state
+└────┬─────┘
+     │ data received
+     ▼
+  ┌──────┐
+  │ live │ ← Normal operation
+  └──┬───┘
+     │ time > staleThreshold
+     ▼
+  ┌───────┐
+  │ stale │ ← Data is old but usable
+  └──┬───┘
+     │ time > maxStaleAge OR fetch error
+     ▼
+  ┌───────┐
+  │ error │ ← Data may be stale, show error UI
+  └──┬───┘
+     │ successful refetch
+     ▼
+  ┌──────┐
+  │ live │ ← Back to normal
+  └──────┘
+```
+
+## Validation
+
+Use Zod schemas to validate incoming data:
+
+```tsx
+import { z } from 'zod';
+import { createPulseValidator, PulseValidationError } from '@stackwright-pro/pulse';
+
+const validator = createPulseValidator(MySchema);
+
+// Safe parse - returns null on failure
+const data = validator.safeParse(rawData);
+
+// Throws PulseValidationError on failure with detailed issues
+const data = validator.parse(rawData);
+```
+
+## Best Practices
+
+1. **Use appropriate intervals** - Consider network cost vs. data freshness needs
+2. **Handle empty states** - Always provide `emptyState` for collections
+3. **Validate early** - Use Zod schemas to catch data contract issues
+4. **Leverage meta state** - Use `meta.state` for fine-grained UI control
+5. **Cleanup properly** - Disable polling when component unmounts if needed
+
+## Live Demo
+
+See the [Marine Logistics Demo](../../examples/marine-logistics-demo/) for a complete example of Pulse with OpenAPI integration:
+
+```tsx
+import { Pulse, PulseIndicator } from '@stackwright-pro/pulse';
+import { createOpenAPIFetcher } from '@stackwright-pro/openapi';
+import type { Equipment } from './generated/types';
+import { EquipmentSchema } from './generated/schemas';
+
+// Create typed fetcher from OpenAPI config
+const fetcher = createOpenAPIFetcher({
+  baseUrl: 'https://api.logistics.example.mil/v1',
+  endpoint: '/equipment',
+  auth: { type: 'bearer', token: process.env.API_TOKEN },
+});
+
+function EquipmentDashboard() {
+  return (
+    <Pulse
+      fetcher={fetcher}
+      interval={5000}
+      staleThreshold={30000}
+      maxStaleAge={60000}
+      schema={EquipmentSchema}
+      loadingState={<SkeletonLoader />}
+    >
+      {(equipment: Equipment[], meta) => (
+        <>
+          <PulseIndicator meta={meta} />
+          <div className="equipment-grid">
+            {equipment.map((item) => (
+              <EquipmentCard key={item.id} data={item} />
+            ))}
+          </div>
+        </>
+      )}
+    </Pulse>
+  );
+}
+```
+
+For a full working demo, see [examples/marine-logistics-demo/src/pages/dashboard-live.tsx](../../examples/marine-logistics-demo/src/pages/dashboard-live.tsx)
+
+## Future Features
+
+- [ ] `createWebSocketFetcher()` - Real-time WebSocket adapter
+- [ ] `createGraphQLFetcher()` - GraphQL query polling adapter
+- [ ] `createSSEFetcher()` - Server-Sent Events adapter
+- [ ] Streaming mode via `useStreaming` hook
+
+See [docs/SOURCE_ADAPTERS.md](./docs/SOURCE_ADAPTERS.md) for planned adapter documentation.
+
+## License
+
+PROPRIETARY - All rights reserved.

package/dist/index.d.mts

@@ -0,0 +1,233 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { ZodSchema, z } from 'zod';
+
+/**
+ * Source-agnostic polling options
+ * The fetcher can be ANY async function - OpenAPI, WebSocket, GraphQL, SSE, etc.
+ */
+interface PulseOptions<T> {
+    /**
+     * ANY async function that returns data
+     * Examples:
+     * - OpenAPI: () => fetch('/api/equipment').then(r => r.json())
+     * - WebSocket: () => websocket.nextMessage()
+     * - GraphQL: () => graphqlClient.query(GET_EQUIPMENT)
+     * - SSE: () => eventSource.nextEvent()
+     */
+    fetcher: () => Promise<T>;
+    /** Polling interval in milliseconds (default: 5000, min: 1000) */
+    interval?: number;
+    /** Show stale warning after this many ms without update (default: 30000) */
+    staleThreshold?: number;
+    /** Show error state after this many ms without update (default: 60000) */
+    maxStaleAge?: number;
+    /** Optional Zod schema for runtime validation */
+    schema?: ZodSchema<T>;
+    /** Enable/disable polling (default: true) */
+    enabled?: boolean;
+    /** React Query option - refetch on window focus (default: true) */
+    refetchOnWindowFocus?: boolean;
+    /** Number of retry attempts on error (default: 3) */
+    retryCount?: number;
+}
+/**
+ * Metadata passed to children render function
+ */
+interface PulseMeta {
+    /** Timestamp of last successful fetch */
+    lastUpdated: Date;
+    /** Data is older than staleThreshold */
+    isStale: boolean;
+    /** Data is older than maxStaleAge or fetch failed */
+    isError: boolean;
+    /** Currently fetching data */
+    isLoading: boolean;
+    /** Number of consecutive errors */
+    errorCount: number;
+    /** Manually trigger a refresh */
+    refetch: () => void;
+    /** Current state: 'loading' | 'live' | 'stale' | 'error' */
+    state: PulseState;
+}
+/** Possible states */
+type PulseState = 'loading' | 'live' | 'stale' | 'error';
+/**
+ * Component props
+ */
+interface PulseProps<T> extends PulseOptions<T> {
+    /** Render prop - receives data and meta */
+    children: (data: T, meta: PulseMeta) => React.ReactNode;
+    /** Initial loading state UI */
+    loadingState?: React.ReactNode;
+    /** Error state UI (receives meta) */
+    errorState?: ((meta: PulseMeta) => React.ReactNode) | React.ReactNode;
+    /** Empty state UI (when fetcher returns empty/null) */
+    emptyState?: React.ReactNode;
+    /** Show stale data while in error state (default: true) */
+    showStaleDataOnError?: boolean;
+}
+/**
+ * Indicator component props
+ */
+interface PulseIndicatorProps {
+    meta: PulseMeta;
+    showSeconds?: boolean;
+    className?: string;
+    labels?: {
+        live?: string;
+        syncing?: string;
+        stale?: string;
+        error?: string;
+    };
+}
+
+/**
+ * Source-agnostic real-time data polling component
+ *
+ * Works with ANY data source via the fetcher prop.
+ * OpenAPI, WebSocket, GraphQL, SSE - doesn't matter.
+ *
+ * @example OpenAPI
+ * ```tsx
+ * <Pulse
+ *   fetcher={() => fetch('/api/equipment').then(r => r.json())}
+ *   interval={5000}
+ *   schema={EquipmentSchema}
+ * >
+ *   {(equipment, meta) => (
+ *     <>
+ *       <PulseIndicator meta={meta} />
+ *       <EquipmentGrid data={equipment} />
+ *     </>
+ *   )}
+ * </Pulse>
+ * ```
+ */
+declare function Pulse<T>({ fetcher, interval, staleThreshold, maxStaleAge, schema, enabled, refetchOnWindowFocus, retryCount, children, loadingState, errorState, emptyState, showStaleDataOnError, }: PulseProps<T>): react_jsx_runtime.JSX.Element;
+
+/**
+ * Visual status indicator for Pulse data
+ * Shows live/syncing/stale/error states with animated dot
+ */
+declare function PulseIndicator({ meta, showSeconds, className, labels, }: PulseIndicatorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Loading state component
+ */
+declare function PulseLoadingState({ className, text, }: {
+    className?: string;
+    text?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Error state component
+ */
+declare function PulseErrorState({ meta, className, customMessage, }: {
+    meta: PulseMeta;
+    className?: string;
+    customMessage?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Empty state component
+ */
+declare function PulseEmptyState({ className, text, }: {
+    className?: string;
+    text?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Stale state component
+ */
+declare function PulseStaleState({ meta, className, customMessage, }: {
+    meta: PulseMeta;
+    className?: string;
+    customMessage?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Syncing state component
+ */
+declare function PulseSyncingState({ className, text, }: {
+    className?: string;
+    text?: string;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Source-agnostic polling hook
+ *
+ * Works with ANY fetcher function:
+ * - OpenAPI endpoints
+ * - WebSocket messages
+ * - GraphQL queries
+ * - SSE events
+ * - Custom fetch functions
+ */
+declare function usePulse<T>(options: PulseOptions<T>): {
+    data: T | undefined;
+    meta: PulseMeta;
+    state: PulseState;
+    error: Error | null;
+};
+
+/**
+ * useStreaming - Future streaming mode hook
+ *
+ * This hook is a placeholder for future streaming support.
+ * Planned implementation will support:
+ * - Server-Sent Events (SSE)
+ * - WebSocket streams
+ * - Chunked transfer encoding
+ * - Real-time push notifications
+ *
+ * @example Future usage
+ * ```tsx
+ * const { data, isConnected } = useStreaming({
+ *   url: '/api/events',
+ *   type: 'sse',
+ *   onMessage: (event) => handleEvent(event),
+ * });
+ * ```
+ */
+declare function useStreaming<T>(_options: StreamingOptions<T>): StreamingResult<T>;
+interface StreamingOptions<T> {
+    url: string;
+    type: 'sse' | 'websocket';
+    onMessage?: (data: T) => void;
+    reconnectInterval?: number;
+    maxRetries?: number;
+}
+interface StreamingResult<T> {
+    data: T | null;
+    isConnected: boolean;
+    isConnecting: boolean;
+    error: Error | null;
+}
+
+/**
+ * Creates a validation wrapper for Pulse data
+ */
+declare function createPulseValidator<T>(schema: z.ZodSchema<T>): {
+    /**
+     * Validates data, throwing on failure
+     */
+    parse: (data: unknown) => T;
+    /**
+     * Safe parse - returns null on failure
+     */
+    safeParse: (data: unknown) => T | null;
+};
+/**
+ * Error class for validation failures
+ */
+declare class PulseValidationError extends Error {
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, issues: z.ZodIssue[]);
+    /**
+     * Get formatted error messages
+     */
+    getFormattedErrors(): {
+        path: string;
+        message: string;
+        code: "custom" | "invalid_type" | "too_big" | "too_small" | "invalid_format" | "not_multiple_of" | "unrecognized_keys" | "invalid_union" | "invalid_key" | "invalid_element" | "invalid_value";
+    }[];
+}
+
+export { Pulse, PulseEmptyState, PulseErrorState, PulseIndicator, type PulseIndicatorProps, PulseLoadingState, type PulseMeta, type PulseOptions, type PulseProps, PulseStaleState, type PulseState, PulseSyncingState, PulseValidationError, createPulseValidator, usePulse, useStreaming };