zyflow 0.6.4

package/src/api/errors.ts

@@ -0,0 +1,123 @@
+/**
+ * API Error Handling
+ *
+ * Custom error classes for API-specific errors
+ */
+
+/**
+ * Base API Error class
+ * Extends Error to provide structured API error information
+ */
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code?: string,
+    public details?: unknown
+  ) {
+    super(message)
+    this.name = 'ApiError'
+    Object.setPrototypeOf(this, ApiError.prototype)
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      details: this.details,
+    }
+  }
+}
+
+/**
+ * Timeout error for API requests that exceed the timeout limit
+ */
+export class TimeoutError extends ApiError {
+  constructor(message = 'Request timeout') {
+    super(message, 408, 'TIMEOUT')
+    this.name = 'TimeoutError'
+    Object.setPrototypeOf(this, TimeoutError.prototype)
+  }
+}
+
+/**
+ * Network error for connectivity issues
+ */
+export class NetworkError extends ApiError {
+  constructor(message = 'Network error', public originalError?: Error) {
+    super(message, 0, 'NETWORK_ERROR')
+    this.name = 'NetworkError'
+    Object.setPrototypeOf(this, NetworkError.prototype)
+  }
+}
+
+/**
+ * Validation error for request validation failures
+ */
+export class ValidationError extends ApiError {
+  constructor(message: string, public validationErrors?: Record<string, string[]>) {
+    super(message, 400, 'VALIDATION_ERROR')
+    this.name = 'ValidationError'
+    Object.setPrototypeOf(this, ValidationError.prototype)
+  }
+}
+
+/**
+ * Type guard to check if an error is an ApiError
+ */
+export function isApiError(error: unknown): error is ApiError {
+  return error instanceof ApiError
+}
+
+/**
+ * Type guard to check if an error is a TimeoutError
+ */
+export function isTimeoutError(error: unknown): error is TimeoutError {
+  return error instanceof TimeoutError
+}
+
+/**
+ * Type guard to check if an error is a NetworkError
+ */
+export function isNetworkError(error: unknown): error is NetworkError {
+  return error instanceof NetworkError
+}
+
+/**
+ * Type guard to check if an error is a ValidationError
+ */
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError
+}
+
+/**
+ * Get user-friendly error message
+ */
+export function getErrorMessage(error: unknown): string {
+  if (isApiError(error)) {
+    return error.message
+  }
+
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return String(error)
+}
+
+/**
+ * Get error code for logging/tracking
+ */
+export function getErrorCode(error: unknown): string {
+  if (isApiError(error)) {
+    return error.code || 'API_ERROR'
+  }
+
+  if (error instanceof Error) {
+    return error.name
+  }
+
+  return 'UNKNOWN_ERROR'
+}

package/src/api/flow.ts

@@ -0,0 +1,233 @@
+/**
+ * Flow API with MoAI SPEC Support
+ *
+ * Handles both OpenSpec and MoAI SPEC response formats using discriminated unions
+ */
+
+import { api } from './client'
+import type { FlowItem, OpenSpecChangeWithType, MoaiSpecWithType, FlowChange, FlowTask, FlowSyncResponse, FlowChangeCountsResponse } from '@/types'
+import { isOpenSpecChange, isMoaiSpec } from '@/types'
+
+// =============================================
+// Response Type Handlers
+// =============================================
+
+/**
+ * Parse flow item response and ensure proper discriminator
+ */
+export function parseFlowItem(data: unknown): FlowItem | null {
+  if (!data || typeof data !== 'object') {
+    return null
+  }
+
+  const item = data as Record<string, unknown>
+
+  // Check discriminator field
+  if (item.type === 'openspec') {
+    return item as unknown as OpenSpecChangeWithType
+  } else if (item.type === 'spec') {
+    return item as unknown as MoaiSpecWithType
+  }
+
+  // Default to OpenSpec for backward compatibility
+  return {
+    ...item,
+    type: 'openspec',
+  } as unknown as OpenSpecChangeWithType
+}
+
+/**
+ * Parse array of flow items
+ */
+export function parseFlowItems(items: unknown[]): FlowItem[] {
+  if (!Array.isArray(items)) {
+    return []
+  }
+
+  return items
+    .map(item => parseFlowItem(item))
+    .filter((item): item is FlowItem => item !== null)
+}
+
+// =============================================
+// Flow API Endpoints
+// =============================================
+
+export const flowApi = {
+  /**
+   * List all flow changes (supports both OpenSpec and MoAI SPEC formats)
+   */
+  listChanges: async (): Promise<FlowItem[]> => {
+    const response = await api.get<{ changes: unknown[] }>('/api/flow/changes')
+    return parseFlowItems(response.changes)
+  },
+
+  /**
+   * Get change counts with detailed breakdown
+   */
+  getChangeCounts: async (status?: string): Promise<FlowChangeCountsResponse> => {
+    return api.get<FlowChangeCountsResponse>(
+      `/api/flow/changes/counts${status ? `?status=${status}` : ''}`
+    )
+  },
+
+  /**
+   * Get a single flow change with all details
+   */
+  getChange: async (changeId: string): Promise<{ change: FlowChange; stages: Record<string, unknown> }> => {
+    return api.get<{ change: FlowChange; stages: Record<string, unknown> }>(
+      `/api/flow/changes/${changeId}`
+    )
+  },
+
+  /**
+   * Sync all flow changes
+   */
+  syncChanges: async (): Promise<FlowSyncResponse> => {
+    return api.post<FlowSyncResponse>('/api/flow/sync')
+  },
+
+  /**
+   * Sync all changes across projects
+   */
+  syncAllChanges: async (): Promise<FlowSyncResponse> => {
+    return api.post<FlowSyncResponse>('/api/flow/sync/all')
+  },
+
+  /**
+   * Sync a specific change
+   */
+  syncChange: async (changeId: string): Promise<{ changeId: string; tasksCreated: number; tasksUpdated: number }> => {
+    return api.post<{ changeId: string; tasksCreated: number; tasksUpdated: number }>(
+      `/api/flow/changes/${changeId}/sync`
+    )
+  },
+
+  /**
+   * Archive a change
+   */
+  archiveChange: async (
+    changeId: string,
+    options?: { skipSpecs?: boolean; force?: boolean }
+  ): Promise<{ changeId: string; archived: boolean; filesMoved: boolean }> => {
+    return api.post<{ changeId: string; archived: boolean; filesMoved: boolean }>(
+      `/api/flow/changes/${changeId}/archive`,
+      options
+    )
+  },
+
+  /**
+   * Fix validation errors for a change
+   */
+  fixValidation: async (changeId: string): Promise<{ changeId: string; proposalFixed: boolean; specsFixed: number }> => {
+    return api.post<{ changeId: string; proposalFixed: boolean; specsFixed: number }>(
+      `/api/flow/changes/${changeId}/fix-validation`
+    )
+  },
+
+  /**
+   * Get proposal content for a change
+   */
+  getProposal: async (changeId: string): Promise<{ changeId: string; content: string | null }> => {
+    return api.get<{ changeId: string; content: string | null }>(
+      `/api/flow/changes/${changeId}/proposal`
+    )
+  },
+
+  /**
+   * Get design content for a change
+   */
+  getDesign: async (changeId: string): Promise<{ changeId: string; content: string | null }> => {
+    return api.get<{ changeId: string; content: string | null }>(
+      `/api/flow/changes/${changeId}/design`
+    )
+  },
+
+  /**
+   * Get spec content for a change
+   */
+  getSpec: async (changeId: string): Promise<{ changeId: string; content: string | null; specId: string | null }> => {
+    return api.get<{ changeId: string; content: string | null; specId: string | null }>(
+      `/api/flow/changes/${changeId}/spec`
+    )
+  },
+
+  /**
+   * Get specific spec by ID
+   */
+  getSpecById: async (changeId: string, specId: string): Promise<{ specId: string; content: string | null; location: string | null }> => {
+    return api.get<{ specId: string; content: string | null; location: string | null }>(
+      `/api/flow/changes/${changeId}/specs/${specId}`
+    )
+  },
+
+  /**
+   * List flow tasks with optional filters
+   */
+  listTasks: async (params?: {
+    changeId?: string
+    stage?: string
+    status?: string
+    standalone?: boolean
+    includeArchived?: boolean
+  }): Promise<{ tasks: FlowTask[] }> => {
+    const searchParams = new URLSearchParams()
+    if (params?.changeId) searchParams.set('changeId', params.changeId)
+    if (params?.stage) searchParams.set('stage', params.stage)
+    if (params?.status) searchParams.set('status', params.status)
+    if (params?.standalone) searchParams.set('standalone', 'true')
+    if (params?.includeArchived) searchParams.set('includeArchived', 'true')
+    const query = searchParams.toString()
+    return api.get<{ tasks: FlowTask[] }>(
+      `/api/flow/tasks${query ? `?${query}` : ''}`
+    )
+  },
+
+  /**
+   * Create a new flow task
+   */
+  createTask: async (data: {
+    changeId?: string
+    stage?: string
+    title: string
+    description?: string
+    priority?: string
+  }): Promise<{ task: FlowTask }> => {
+    return api.post<{ task: FlowTask }>('/api/flow/tasks', data)
+  },
+
+  /**
+   * Update a flow task
+   */
+  updateTask: async (taskId: string, data: Record<string, unknown>): Promise<{ task: FlowTask }> => {
+    return api.patch<{ task: FlowTask }>(`/api/flow/tasks/${taskId}`, data)
+  },
+}
+
+// =============================================
+// Type Assertion Helpers
+// =============================================
+
+/**
+ * Assert that a FlowItem is an OpenSpec change
+ * Throws error if not
+ */
+export function assertOpenSpecChange(item: FlowItem): OpenSpecChangeWithType {
+  if (!isOpenSpecChange(item)) {
+    throw new Error(`Expected OpenSpec change but got: ${item.type}`)
+  }
+  return item
+}
+
+/**
+ * Assert that a FlowItem is a MoAI SPEC
+ * Throws error if not
+ */
+export function assertMoaiSpec(item: FlowItem): MoaiSpecWithType {
+  if (!isMoaiSpec(item)) {
+    throw new Error(`Expected MoAI SPEC but got: ${item.type}`)
+  }
+  return item
+}
+
+export default flowApi

package/src/api/offline-queue.ts

@@ -0,0 +1,351 @@
+/**
+ * Offline Queue Manager
+ *
+ * Manages queuing and synchronization of API requests during offline mode
+ * Persists queue to localStorage for recovery across sessions
+ *
+ * @module api/offline-queue
+ */
+
+import { useOfflineStore, QueuedOperation } from '@/stores/offlineStore'
+import { api } from './client'
+
+// =============================================
+// Constants
+// =============================================
+
+const OFFLINE_QUEUE_KEY = 'zyflow_offline_queue'
+const OFFLINE_QUEUE_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
+
+// =============================================
+// Types
+// =============================================
+
+export interface SyncResult {
+  successful: QueuedOperation[]
+  failed: Array<{
+    operation: QueuedOperation
+    error: string
+  }>
+  skipped: QueuedOperation[]
+}
+
+export interface OfflineQueueOptions {
+  /** Persist queue to localStorage (default: true) */
+  persist?: boolean
+  /** Auto-sync when coming online (default: true) */
+  autoSync?: boolean
+  /** Callback when sync completes */
+  onSyncComplete?: (result: SyncResult) => void
+  /** Callback when sync error occurs */
+  onSyncError?: (error: Error) => void
+}
+
+// =============================================
+// Offline Queue Manager Class
+// =============================================
+
+export class OfflineQueueManager {
+  private options: OfflineQueueOptions
+  private isSyncing = false
+
+  constructor(options: OfflineQueueOptions = {}) {
+    this.options = {
+      persist: options.persist !== false,
+      autoSync: options.autoSync !== false,
+      onSyncComplete: options.onSyncComplete,
+      onSyncError: options.onSyncError,
+    }
+
+    // Load persisted queue on init
+    if (this.options.persist) {
+      this.loadFromStorage()
+    }
+  }
+
+  /**
+   * Queue an operation for later execution
+   */
+  queueOperation(
+    type: QueuedOperation['type'],
+    endpoint: string,
+    method: string,
+    body?: unknown
+  ): string {
+    return useOfflineStore.getState().addToQueue({
+      type,
+      endpoint,
+      method,
+      body,
+    })
+  }
+
+  /**
+   * Synchronize queued operations
+   */
+  async sync(): Promise<SyncResult> {
+    if (this.isSyncing) {
+      console.warn('Sync already in progress')
+      return { successful: [], failed: [], skipped: [] }
+    }
+
+    this.isSyncing = true
+    const store = useOfflineStore.getState()
+    store.setSyncing(true)
+
+    const queue = [...store.getAllQueued()]
+    const result: SyncResult = {
+      successful: [],
+      failed: [],
+      skipped: [],
+    }
+
+    try {
+      for (let i = 0; i < queue.length; i++) {
+        const operation = queue[i]
+        const total = queue.length
+
+        // Update progress
+        store.updateSyncProgress(i, total)
+
+        try {
+          // Execute the operation
+          await this.executeOperation(operation)
+
+          // Remove from queue on success
+          store.removeFromQueue(operation.id)
+          result.successful.push(operation)
+        } catch (error) {
+          // Check max retries
+          const maxRetries = store.maxRetries
+          if (operation.retryCount >= maxRetries) {
+            // Max retries exceeded, remove from queue
+            store.removeFromQueue(operation.id)
+            result.failed.push({
+              operation,
+              error: error instanceof Error ? error.message : String(error),
+            })
+          } else {
+            // Increment retry count and keep in queue
+            store.incrementRetryCount(operation.id)
+            store.setOperationError(
+              operation.id,
+              error instanceof Error ? error.message : String(error)
+            )
+            result.skipped.push(operation)
+          }
+        }
+      }
+
+      // Persist updated queue
+      if (this.options.persist) {
+        this.saveToStorage()
+      }
+
+      // Mark sync complete
+      store.markSyncComplete()
+      this.options.onSyncComplete?.(result)
+    } catch (error) {
+      store.setSyncError(
+        error instanceof Error ? error.message : 'Unknown error'
+      )
+      this.options.onSyncError?.(
+        error instanceof Error ? error : new Error(String(error))
+      )
+    } finally {
+      this.isSyncing = false
+    }
+
+    return result
+  }
+
+  /**
+   * Execute a single queued operation
+   */
+  private async executeOperation(operation: QueuedOperation): Promise<void> {
+    const method = operation.method.toUpperCase()
+
+    switch (method) {
+      case 'GET':
+        await api.get(operation.endpoint)
+        break
+
+      case 'POST':
+        await api.post(operation.endpoint, operation.body)
+        break
+
+      case 'PUT':
+        await api.put(operation.endpoint, operation.body)
+        break
+
+      case 'PATCH':
+        await api.patch(operation.endpoint, operation.body)
+        break
+
+      case 'DELETE':
+        await api.delete(operation.endpoint)
+        break
+
+      default:
+        throw new Error(`Unsupported HTTP method: ${method}`)
+    }
+  }
+
+  /**
+   * Clear all queued operations
+   */
+  clear(): void {
+    useOfflineStore.getState().clearQueue()
+    if (this.options.persist) {
+      this.clearStorage()
+    }
+  }
+
+  /**
+   * Get current queue
+   */
+  getQueue(): QueuedOperation[] {
+    return useOfflineStore.getState().getAllQueued()
+  }
+
+  /**
+   * Get queue size
+   */
+  getQueueSize(): number {
+    return useOfflineStore.getState().queue.length
+  }
+
+  /**
+   * Check if queue has operations
+   */
+  hasQueuedOperations(): boolean {
+    return useOfflineStore.getState().queue.length > 0
+  }
+
+  /**
+   * Save queue to localStorage
+   */
+  private saveToStorage(): void {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return
+
+      const queue = useOfflineStore.getState().getAllQueued()
+      localStorage.setItem(OFFLINE_QUEUE_KEY, JSON.stringify(queue))
+    } catch (error) {
+      console.warn('Failed to save offline queue to storage', error)
+    }
+  }
+
+  /**
+   * Load queue from localStorage
+   */
+  private loadFromStorage(): void {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return
+
+      const stored = localStorage.getItem(OFFLINE_QUEUE_KEY)
+      if (!stored) return
+
+      const queue = JSON.parse(stored) as QueuedOperation[]
+      const store = useOfflineStore.getState()
+
+      // Add stored operations back to queue
+      queue.forEach((op) => {
+        store.addToQueue({
+          type: op.type,
+          endpoint: op.endpoint,
+          method: op.method,
+          body: op.body,
+        })
+      })
+    } catch (error) {
+      console.warn('Failed to load offline queue from storage', error)
+    }
+  }
+
+  /**
+   * Clear localStorage
+   */
+  private clearStorage(): void {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return
+      localStorage.removeItem(OFFLINE_QUEUE_KEY)
+    } catch (error) {
+      console.warn('Failed to clear offline queue storage', error)
+    }
+  }
+
+  /**
+   * Clean up expired operations (older than 7 days)
+   */
+  cleanupExpired(): number {
+    return useOfflineStore.getState().clearExpiredOperations(OFFLINE_QUEUE_EXPIRY_MS)
+  }
+}
+
+// =============================================
+// Singleton Instance
+// =============================================
+
+let queueManagerInstance: OfflineQueueManager | null = null
+
+export function getOfflineQueueManager(
+  options?: OfflineQueueOptions
+): OfflineQueueManager {
+  if (!queueManagerInstance) {
+    queueManagerInstance = new OfflineQueueManager(options)
+  }
+  return queueManagerInstance
+}
+
+/**
+ * Initialize offline queue manager with options
+ */
+export function initializeOfflineQueue(options: OfflineQueueOptions): void {
+  queueManagerInstance = new OfflineQueueManager(options)
+}
+
+/**
+ * Reset offline queue manager
+ */
+export function resetOfflineQueue(): void {
+  queueManagerInstance?.clear()
+  queueManagerInstance = null
+}
+
+// =============================================
+// Utility Functions
+// =============================================
+
+/**
+ * Quick queue an operation
+ */
+export function queueOperation(
+  type: QueuedOperation['type'],
+  endpoint: string,
+  method: string,
+  body?: unknown
+): string {
+  return getOfflineQueueManager().queueOperation(type, endpoint, method, body)
+}
+
+/**
+ * Quick sync
+ */
+export function syncOfflineQueue(): Promise<SyncResult> {
+  return getOfflineQueueManager().sync()
+}
+
+/**
+ * Check if there are queued operations
+ */
+export function hasQueuedOperations(): boolean {
+  return getOfflineQueueManager().hasQueuedOperations()
+}
+
+/**
+ * Get queued operations count
+ */
+export function getQueuedOperationsCount(): number {
+  return getOfflineQueueManager().getQueueSize()
+}