zyflow 0.6.4

package/src/api/retry-logic.ts

@@ -0,0 +1,233 @@
+/**
+ * Retry Logic with Exponential Backoff
+ *
+ * Implements exponential backoff retry strategy for API requests
+ * - 1st retry: 1 second
+ * - 2nd retry: 2 seconds
+ * - 3rd retry: 4 seconds
+ * - 4th retry: 8 seconds
+ * - 5th retry: 16 seconds (max 30 seconds)
+ *
+ * @module api/retry-logic
+ */
+
+import { ApiError, TimeoutError, NetworkError } from './errors'
+
+// =============================================
+// Types
+// =============================================
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelayMs?: number
+  /** Maximum delay in milliseconds (default: 30000) */
+  maxDelayMs?: number
+  /** Jitter percentage for exponential backoff (default: 0.1 = 10%) */
+  jitterFactor?: number
+  /** HTTP status codes to retry on (default: [408, 429, 500, 502, 503, 504]) */
+  retryableStatusCodes?: number[]
+  /** Custom retry predicate function */
+  shouldRetry?: (error: unknown, attempt: number) => boolean
+}
+
+export interface RetryState {
+  attempt: number
+  delay: number
+  totalDelay: number
+}
+
+// =============================================
+// Default Configuration
+// =============================================
+
+const DEFAULT_MAX_ATTEMPTS = 3
+const DEFAULT_INITIAL_DELAY_MS = 1000
+const DEFAULT_MAX_DELAY_MS = 30000
+const DEFAULT_JITTER_FACTOR = 0.1
+const DEFAULT_RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504]
+
+// =============================================
+// Retry Logic Implementation
+// =============================================
+
+/**
+ * Calculate exponential backoff delay with jitter
+ *
+ * Formula: min(initialDelay * 2^(attempt-1) + jitter, maxDelay)
+ */
+export function calculateBackoffDelay(
+  attempt: number,
+  options: RetryOptions = {}
+): RetryState {
+  const initialDelay = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS
+  const maxDelay = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
+  const jitterFactor = options.jitterFactor ?? DEFAULT_JITTER_FACTOR
+
+  // Calculate exponential backoff: initialDelay * 2^(attempt - 1)
+  const exponentialDelay = initialDelay * Math.pow(2, attempt - 1)
+
+  // Add jitter: ±10% of the calculated delay
+  const jitter = exponentialDelay * jitterFactor * (Math.random() - 0.5) * 2
+  const delayWithJitter = exponentialDelay + jitter
+
+  // Cap at max delay
+  const finalDelay = Math.min(Math.max(delayWithJitter, 0), maxDelay)
+
+  return {
+    attempt,
+    delay: finalDelay,
+    totalDelay: finalDelay * attempt, // Approximation
+  }
+}
+
+/**
+ * Determine if an error should trigger a retry
+ */
+export function shouldRetryError(
+  error: unknown,
+  attempt: number,
+  options: RetryOptions = {}
+): boolean {
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+
+  // Stop retrying if max attempts reached
+  if (attempt > maxAttempts) {
+    return false
+  }
+
+  // Use custom retry predicate if provided
+  if (options.shouldRetry) {
+    return options.shouldRetry(error, attempt)
+  }
+
+  // Network errors are always retryable
+  if (error instanceof NetworkError) {
+    return true
+  }
+
+  // Timeout errors are retryable
+  if (error instanceof TimeoutError) {
+    return true
+  }
+
+  // API errors with retryable status codes are retryable
+  if (error instanceof ApiError) {
+    const retryableStatuses =
+      options.retryableStatusCodes ?? DEFAULT_RETRYABLE_STATUS_CODES
+    return retryableStatuses.includes(error.status)
+  }
+
+  // Other errors are not retried
+  return false
+}
+
+/**
+ * Execute a function with retry logic
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+
+      // Check if we should retry
+      if (!shouldRetryError(error, attempt, options)) {
+        throw error
+      }
+
+      // Calculate backoff delay
+      if (attempt < maxAttempts) {
+        const backoffState = calculateBackoffDelay(attempt, options)
+        await sleep(backoffState.delay)
+      }
+    }
+  }
+
+  // All retries exhausted
+  throw lastError
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// =============================================
+// Public Retry Hook
+// =============================================
+
+/**
+ * Create a retry-enabled request function
+ */
+export function createRetryableRequest<T>(
+  requestFn: () => Promise<T>,
+  options: RetryOptions = {}
+) {
+  return () => withRetry(() => requestFn(), options)
+}
+
+// =============================================
+// Retry State Tracker (for observability)
+// =============================================
+
+export interface RetryTracker {
+  totalAttempts: number
+  successAttempt?: number
+  errors: Array<{ attempt: number; error: unknown; delay: number }>
+}
+
+/**
+ * Execute function with retry tracking
+ */
+export async function withRetryTracking<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<{ result: T; tracker: RetryTracker }> {
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+  const tracker: RetryTracker = {
+    totalAttempts: 0,
+    errors: [],
+  }
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    tracker.totalAttempts = attempt
+
+    try {
+      const result = await fn()
+      tracker.successAttempt = attempt
+      return { result, tracker }
+    } catch (error) {
+      const backoffState = calculateBackoffDelay(attempt, options)
+      tracker.errors.push({
+        attempt,
+        error,
+        delay: backoffState.delay,
+      })
+
+      // Check if we should retry
+      if (!shouldRetryError(error, attempt, options)) {
+        throw error
+      }
+
+      // Wait before next attempt
+      if (attempt < maxAttempts) {
+        await sleep(backoffState.delay)
+      }
+    }
+  }
+
+  // All retries exhausted - throw last error
+  const lastError = tracker.errors[tracker.errors.length - 1]?.error
+  throw lastError ?? new Error('Unknown error after retries')
+}

package/src/components/OfflineModeBanner.tsx

@@ -0,0 +1,159 @@
+/**
+ * Offline Mode Banner Component
+ *
+ * Displays offline status and pending operations
+ * Shows automatic sync progress and manual reconnect button
+ *
+ * @module components/OfflineModeBanner
+ */
+
+import { useEffect, useState } from 'react'
+import { useNetworkStatus } from '@/hooks/useNetworkStatus'
+import { useOfflineStore, selectIsOffline, selectQueueLength, selectIsSyncing, selectSyncProgress } from '@/stores/offlineStore'
+import { getOfflineQueueManager } from '@/api/offline-queue'
+import { AlertCircle, Wifi, WifiOff, RefreshCw, Check } from 'lucide-react'
+
+// =============================================
+// Component
+// =============================================
+
+export function OfflineModeBanner() {
+  const isOffline = useOfflineStore(selectIsOffline)
+  const queueLength = useOfflineStore(selectQueueLength)
+  const isSyncing = useOfflineStore(selectIsSyncing)
+  const syncProgress = useOfflineStore(selectSyncProgress)
+  const [syncComplete, setSyncComplete] = useState(false)
+
+  // Network status monitoring
+  useNetworkStatus({
+    onOnline: async () => {
+      // Auto-sync when coming online
+      const queueManager = getOfflineQueueManager()
+      if (queueManager.hasQueuedOperations()) {
+        await queueManager.sync()
+      }
+    },
+  })
+
+  // Reset sync complete indicator
+  useEffect(() => {
+    if (!isSyncing && syncComplete) {
+      const timer = setTimeout(() => setSyncComplete(false), 2000)
+      return () => clearTimeout(timer)
+    }
+  }, [isSyncing, syncComplete])
+
+  // Update sync complete status
+  useEffect(() => {
+    if (!isSyncing && syncProgress.total > 0 && syncProgress.completed === syncProgress.total) {
+      setSyncComplete(true)
+    }
+  }, [isSyncing, syncProgress])
+
+  // Handle manual sync
+  const handleSync = async () => {
+    const queueManager = getOfflineQueueManager()
+    await queueManager.sync()
+  }
+
+  if (!isOffline) {
+    return null
+  }
+
+  const progressPercent = syncProgress.total > 0 ? (syncProgress.completed / syncProgress.total) * 100 : 0
+
+  return (
+    <div className="fixed top-0 left-0 right-0 z-40 bg-yellow-50 border-b border-yellow-200 px-4 py-3 shadow-sm">
+      <div className="max-w-full mx-auto">
+        {/* Main status row */}
+        <div className="flex items-center justify-between gap-3">
+          {/* Status indicator and text */}
+          <div className="flex items-center gap-3 flex-1 min-w-0">
+            <div className="flex-shrink-0">
+              {syncComplete ? (
+                <Check className="w-5 h-5 text-green-600" />
+              ) : isSyncing ? (
+                <RefreshCw className="w-5 h-5 text-blue-600 animate-spin" />
+              ) : (
+                <WifiOff className="w-5 h-5 text-yellow-600" />
+              )}
+            </div>
+
+            <div className="flex-1 min-w-0">
+              {syncComplete ? (
+                <p className="text-sm font-medium text-green-700">
+                  Sync complete - all changes uploaded
+                </p>
+              ) : isSyncing ? (
+                <div className="space-y-1">
+                  <p className="text-sm font-medium text-blue-700">
+                    Syncing ({syncProgress.completed}/{syncProgress.total})
+                  </p>
+                  <div className="w-full max-w-xs bg-blue-200 rounded-full h-1.5">
+                    <div
+                      className="bg-blue-600 h-1.5 rounded-full transition-all duration-300"
+                      style={{ width: `${progressPercent}%` }}
+                    />
+                  </div>
+                </div>
+              ) : (
+                <div className="space-y-1">
+                  <p className="text-sm font-medium text-yellow-800 flex items-center gap-1">
+                    <AlertCircle className="w-4 h-4" />
+                    Offline - changes will be uploaded when connection restored
+                  </p>
+                  {queueLength > 0 && (
+                    <p className="text-xs text-yellow-700">
+                      {queueLength} pending {queueLength === 1 ? 'change' : 'changes'}
+                    </p>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+
+          {/* Action buttons */}
+          <div className="flex items-center gap-2 flex-shrink-0">
+            {!syncComplete && queueLength > 0 && !isSyncing && (
+              <button
+                onClick={handleSync}
+                className="inline-flex items-center gap-2 px-3 py-1.5 bg-yellow-200 hover:bg-yellow-300 text-yellow-800 rounded text-sm font-medium transition-colors"
+                title="Manually sync pending changes"
+              >
+                <RefreshCw className="w-4 h-4" />
+                Sync Now
+              </button>
+            )}
+
+            {isSyncing && (
+              <div className="flex items-center gap-1 text-xs text-blue-600 font-medium">
+                <RefreshCw className="w-3 h-3 animate-spin" />
+                Syncing...
+              </div>
+            )}
+
+            {syncComplete && (
+              <div className="flex items-center gap-1 text-xs text-green-600 font-medium">
+                <Check className="w-3 h-3" />
+                Synced
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Details row (for dev/debug) */}
+        {process.env.NODE_ENV === 'development' && queueLength > 0 && (
+          <div className="mt-2 text-xs text-yellow-700">
+            Queue size: {queueLength} | Last sync: {useOfflineStore.getState().lastSyncTime ? new Date(useOfflineStore.getState().lastSyncTime!).toLocaleTimeString() : 'Never'}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// =============================================
+// Export
+// =============================================
+
+export default OfflineModeBanner

package/src/components/SSEStatusIndicator.tsx

@@ -0,0 +1,194 @@
+/**
+ * SSE Status Indicator Component
+ *
+ * Displays real-time SSE connection status in the header
+ * Shows connection state with visual indicators
+ *
+ * @module components/SSEStatusIndicator
+ */
+
+import { useSSEStatus } from '@/hooks/useSSEConnection'
+import { useSSEStore, selectConnectionStatus, selectReconnectAttempt, selectMaxReconnectAttempts } from '@/stores/sseStore'
+import { Wifi, WifiOff, AlertCircle, RotateCw } from 'lucide-react'
+
+// =============================================
+// Component
+// =============================================
+
+export function SSEStatusIndicator() {
+  const status = useSSEStore(selectConnectionStatus)
+  const reconnectAttempt = useSSEStore(selectReconnectAttempt)
+  const maxReconnectAttempts = useSSEStore(selectMaxReconnectAttempts)
+  const connectionInfo = useSSEStore((state) => state.connection)
+
+  // Determine display properties
+  const isConnected = status === 'connected'
+  const isConnecting = status === 'connecting'
+  const isReconnecting = status === 'reconnecting'
+  const isFailed = status === 'failed'
+  const isDisconnected = status === 'disconnected'
+
+  // Color and icon based on status
+  const getStatusDisplay = () => {
+    if (isConnected) {
+      return {
+        bgColor: 'bg-green-100',
+        textColor: 'text-green-700',
+        borderColor: 'border-green-300',
+        icon: <Wifi className="w-4 h-4" />,
+        label: 'Connected',
+        tooltip: 'SSE connection is active',
+      }
+    }
+
+    if (isConnecting) {
+      return {
+        bgColor: 'bg-blue-100',
+        textColor: 'text-blue-700',
+        borderColor: 'border-blue-300',
+        icon: <RotateCw className="w-4 h-4 animate-spin" />,
+        label: 'Connecting',
+        tooltip: 'Establishing SSE connection...',
+      }
+    }
+
+    if (isReconnecting) {
+      return {
+        bgColor: 'bg-yellow-100',
+        textColor: 'text-yellow-700',
+        borderColor: 'border-yellow-300',
+        icon: <RotateCw className="w-4 h-4 animate-spin" />,
+        label: `Reconnecting (${reconnectAttempt}/${maxReconnectAttempts})`,
+        tooltip: `Reconnecting... Attempt ${reconnectAttempt} of ${maxReconnectAttempts}`,
+      }
+    }
+
+    if (isFailed) {
+      return {
+        bgColor: 'bg-red-100',
+        textColor: 'text-red-700',
+        borderColor: 'border-red-300',
+        icon: <AlertCircle className="w-4 h-4" />,
+        label: 'Connection Failed',
+        tooltip: `Failed to connect: ${connectionInfo.lastError || 'Unknown error'}`,
+      }
+    }
+
+    // Disconnected
+    return {
+      bgColor: 'bg-gray-100',
+      textColor: 'text-gray-600',
+      borderColor: 'border-gray-300',
+      icon: <WifiOff className="w-4 h-4" />,
+      label: 'Disconnected',
+      tooltip: 'SSE connection is inactive',
+    }
+  }
+
+  const display = getStatusDisplay()
+
+  return (
+    <div
+      className={`flex items-center gap-2 px-3 py-1.5 rounded border ${display.bgColor} ${display.borderColor} ${display.textColor} text-sm font-medium transition-all`}
+      title={display.tooltip}
+    >
+      <span className="flex-shrink-0">{display.icon}</span>
+      <span className="hidden sm:inline flex-shrink-0">{display.label}</span>
+
+      {/* Compact version for mobile */}
+      {isConnected && (
+        <span className="sm:hidden flex-shrink-0 w-2 h-2 rounded-full bg-green-600" />
+      )}
+      {isReconnecting && (
+        <span className="sm:hidden flex-shrink-0 text-xs">
+          {reconnectAttempt}/{maxReconnectAttempts}
+        </span>
+      )}
+      {isFailed && (
+        <span className="sm:hidden flex-shrink-0 w-2 h-2 rounded-full bg-red-600" />
+      )}
+      {isDisconnected && (
+        <span className="sm:hidden flex-shrink-0 w-2 h-2 rounded-full bg-gray-400" />
+      )}
+    </div>
+  )
+}
+
+// =============================================
+// Detailed Status Component (for debugging)
+// =============================================
+
+export function SSEStatusDetailed() {
+  const connectionInfo = useSSEStore((state) => state.connection)
+  const queuedEventsCount = useSSEStore((state) => state.queuedEvents.length)
+
+  return (
+    <div className="space-y-2 rounded border border-gray-200 bg-white p-3 text-xs">
+      <div>
+        <span className="font-semibold">Status:</span> {connectionInfo.status}
+      </div>
+
+      <div>
+        <span className="font-semibold">Reconnect Attempt:</span>{' '}
+        {connectionInfo.reconnectAttempt}/{connectionInfo.maxReconnectAttempts}
+      </div>
+
+      {connectionInfo.lastConnectionTime && (
+        <div>
+          <span className="font-semibold">Last Connected:</span>{' '}
+          {new Date(connectionInfo.lastConnectionTime).toLocaleTimeString()}
+        </div>
+      )}
+
+      {connectionInfo.lastDisconnectionTime && (
+        <div>
+          <span className="font-semibold">Last Disconnected:</span>{' '}
+          {new Date(connectionInfo.lastDisconnectionTime).toLocaleTimeString()}
+        </div>
+      )}
+
+      {connectionInfo.lastError && (
+        <div>
+          <span className="font-semibold">Last Error:</span> {connectionInfo.lastError}
+        </div>
+      )}
+
+      {connectionInfo.nextRetryIn && (
+        <div>
+          <span className="font-semibold">Next Retry In:</span>{' '}
+          {(connectionInfo.nextRetryIn / 1000).toFixed(1)}s
+        </div>
+      )}
+
+      {queuedEventsCount > 0 && (
+        <div className="text-yellow-600">
+          <span className="font-semibold">Queued Events:</span> {queuedEventsCount}
+        </div>
+      )}
+    </div>
+  )
+}
+
+// =============================================
+// Minimal Dot Indicator (for header)
+// =============================================
+
+export function SSEStatusDot() {
+  const status = useSSEStore(selectConnectionStatus)
+
+  let bgColor = 'bg-gray-400'
+
+  if (status === 'connected') {
+    bgColor = 'bg-green-500'
+  } else if (status === 'connecting' || status === 'reconnecting') {
+    bgColor = 'bg-yellow-500 animate-pulse'
+  } else if (status === 'failed') {
+    bgColor = 'bg-red-500'
+  }
+
+  return (
+    <div className={`w-2 h-2 rounded-full ${bgColor}`} title={`SSE Status: ${status}`} />
+  )
+}
+
+export default SSEStatusIndicator