zyflow 0.6.4

package/src/api/client.ts

@@ -0,0 +1,346 @@
+/**
+ * API Client
+ *
+ * 중앙화된 API 요청 처리 및 에러 핸들링
+ * - Retry logic with exponential backoff
+ * - Request/response interception and logging
+ * - Sensitive data filtering
+ */
+
+import { API_BASE_URL } from '@/config/api'
+import type { ApiResponse } from '@/types'
+import { ApiError, TimeoutError, NetworkError } from './errors'
+import { getRequestInterceptor, type InterceptorOptions } from './error-interceptor'
+
+// API 요청 옵션 타입
+interface RequestOptions extends Omit<RequestInit, 'body'> {
+  body?: unknown
+  timeout?: number
+  // 재시도 옵션
+  retryOptions?: {
+    maxAttempts?: number
+    initialDelayMs?: number
+    maxDelayMs?: number
+  }
+  // 인터셉터 옵션
+  logRequests?: boolean
+  logResponses?: boolean
+  logToStore?: boolean
+}
+
+// 기본 요청 타임아웃 (30초)
+const DEFAULT_TIMEOUT = 30000
+
+/**
+ * Parse JSON response with fallback
+ */
+async function parseJson<T>(response: Response): Promise<T | null> {
+  try {
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 공통 fetch 래퍼 (재시도 로직 및 인터셉터 포함)
+ */
+export async function request<T>(
+  url: string,
+  options: RequestOptions = {}
+): Promise<T> {
+  const {
+    body,
+    timeout = DEFAULT_TIMEOUT,
+    retryOptions,
+    logRequests = true,
+    logResponses = true,
+    logToStore = true,
+    ...fetchOptions
+  } = options
+
+  const interceptor = getRequestInterceptor({
+    logRequests,
+    logResponses,
+    logToStore,
+    retry: retryOptions,
+  })
+
+  const requestContext = {
+    url,
+    method: (fetchOptions.method || 'GET').toUpperCase(),
+    headers: fetchOptions.headers as Record<string, string> | undefined,
+    body,
+    timestamp: Date.now(),
+  }
+
+  try {
+    const result = await interceptor.intercept(
+      () => performRequest<T>(url, { body, timeout, ...fetchOptions }),
+      requestContext
+    )
+    return result
+  } catch (error) {
+    interceptor.handleError(error, requestContext)
+    throw error
+  }
+}
+
+/**
+ * Perform actual fetch request
+ */
+async function performRequest<T>(
+  url: string,
+  options: RequestOptions & { timeout: number }
+): Promise<T> {
+  const { body, timeout = DEFAULT_TIMEOUT, ...fetchOptions } = options
+
+  // AbortController를 사용한 타임아웃 처리
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort(), timeout)
+
+  try {
+    const response = await fetch(url, {
+      ...fetchOptions,
+      signal: controller.signal,
+      headers: {
+        'Content-Type': 'application/json',
+        ...fetchOptions.headers,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    clearTimeout(timeoutId)
+
+    // HTTP 에러 처리
+    if (!response.ok) {
+      const errorData = await parseJson<{ error?: string; code?: string; details?: unknown }>(response)
+      const errorMessage = errorData?.error || `HTTP ${response.status}: ${response.statusText}`
+
+      throw new ApiError(
+        errorMessage,
+        response.status,
+        errorData?.code,
+        errorData?.details
+      )
+    }
+
+    const json = await parseJson<ApiResponse<T>>(response)
+
+    if (!json) {
+      throw new ApiError('Failed to parse response', 0)
+    }
+
+    // API 응답 에러 처리
+    if (!json.success) {
+      throw new ApiError(
+        json.error || 'Unknown error',
+        response.status,
+        undefined
+      )
+    }
+
+    if (!json.data) {
+      throw new ApiError('No data in response', response.status)
+    }
+
+    return json.data
+  } catch (error) {
+    clearTimeout(timeoutId)
+
+    if (error instanceof ApiError) {
+      throw error
+    }
+
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        throw new TimeoutError('Request timeout')
+      }
+      throw new NetworkError(error.message, error)
+    }
+
+    throw new ApiError('Unknown error', 0)
+  }
+}
+
+/**
+ * API 클라이언트 객체
+ */
+export const api = {
+  /**
+   * GET 요청
+   */
+  get: <T>(endpoint: string, options?: RequestOptions) =>
+    request<T>(`${API_BASE_URL}${endpoint}`, { ...options, method: 'GET' }),
+
+  /**
+   * POST 요청
+   */
+  post: <T>(endpoint: string, body?: unknown, options?: RequestOptions) =>
+    request<T>(`${API_BASE_URL}${endpoint}`, { ...options, method: 'POST', body }),
+
+  /**
+   * PUT 요청
+   */
+  put: <T>(endpoint: string, body?: unknown, options?: RequestOptions) =>
+    request<T>(`${API_BASE_URL}${endpoint}`, { ...options, method: 'PUT', body }),
+
+  /**
+   * PATCH 요청
+   */
+  patch: <T>(endpoint: string, body?: unknown, options?: RequestOptions) =>
+    request<T>(`${API_BASE_URL}${endpoint}`, { ...options, method: 'PATCH', body }),
+
+  /**
+   * DELETE 요청
+   */
+  delete: <T>(endpoint: string, options?: RequestOptions) =>
+    request<T>(`${API_BASE_URL}${endpoint}`, { ...options, method: 'DELETE' }),
+}
+
+/**
+ * 도메인별 API 클라이언트
+ */
+export const projectsApi = {
+  list: () => api.get<{ projects: unknown[]; activeProjectId: string | null }>('/api/projects'),
+
+  getAllData: () => api.get<unknown>('/api/projects/all-data'),
+
+  browse: () => api.post<{ path: string | null; cancelled: boolean }>('/api/projects/browse'),
+
+  add: (path: string) => api.post<{ project: unknown }>('/api/projects', { path }),
+
+  remove: (projectId: string) => api.delete<void>(`/api/projects/${projectId}`),
+
+  activate: (projectId: string) => api.put<{ project: unknown }>(`/api/projects/${projectId}/activate`),
+
+  updateName: (projectId: string, name: string) =>
+    api.put<{ project: unknown }>(`/api/projects/${projectId}/name`, { name }),
+
+  updatePath: (projectId: string, path: string) =>
+    api.put<{ project: unknown }>(`/api/projects/${projectId}/path`, { path }),
+
+  reorder: (projectIds: string[]) =>
+    api.put<{ projects: unknown[] }>('/api/projects/reorder', { projectIds }),
+
+  getChanges: (projectId: string) =>
+    api.get<{ changes: unknown[] }>(`/api/projects/${projectId}/changes`),
+}
+
+export const changesApi = {
+  list: () => api.get<{ changes: unknown[] }>('/api/changes'),
+
+  listArchived: () => api.get<{ changes: unknown[] }>('/api/changes/archived'),
+
+  getArchived: (changeId: string) => api.get<{ id: string; files: Record<string, string> }>(`/api/changes/archived/${changeId}`),
+
+  getTasks: (changeId: string) => api.get<unknown>(`/api/changes/${changeId}/tasks`),
+
+  toggleTask: (changeId: string, taskId: string) =>
+    api.patch<{ task: unknown }>(`/api/changes/tasks/${changeId}/${taskId}`),
+
+  getPlan: (changeId: string, taskId: string) =>
+    api.get<{ taskId: string; changeId: string; content: string | null; exists: boolean }>(
+      `/api/changes/plans/${changeId}/${taskId}`
+    ),
+}
+
+export const flowApi = {
+  listChanges: () => api.get<{ changes: unknown[] }>('/api/flow/changes'),
+
+  getChangeCounts: (status?: string) =>
+    api.get<{ counts: Record<string, number>; detailed: Record<string, unknown> }>(
+      `/api/flow/changes/counts${status ? `?status=${status}` : ''}`
+    ),
+
+  getChange: (changeId: string) => api.get<{ change: unknown; stages: unknown }>(`/api/flow/changes/${changeId}`),
+
+  syncChanges: () => api.post<{ synced: number; created: number; updated: number; projects: number }>('/api/flow/sync'),
+
+  syncAllChanges: () =>
+    api.post<{ synced: number; created: number; updated: number; projects: number }>('/api/flow/sync/all'),
+
+  syncChange: (changeId: string) =>
+    api.post<{ changeId: string; tasksCreated: number; tasksUpdated: number }>(`/api/flow/changes/${changeId}/sync`),
+
+  archiveChange: (changeId: string, options?: { skipSpecs?: boolean; force?: boolean }) =>
+    api.post<{ changeId: string; archived: boolean; filesMoved: boolean }>(`/api/flow/changes/${changeId}/archive`, options),
+
+  fixValidation: (changeId: string) =>
+    api.post<{ changeId: string; proposalFixed: boolean; specsFixed: number }>(`/api/flow/changes/${changeId}/fix-validation`),
+
+  getProposal: (changeId: string) => api.get<{ changeId: string; content: string | null }>(`/api/flow/changes/${changeId}/proposal`),
+
+  getDesign: (changeId: string) => api.get<{ changeId: string; content: string | null }>(`/api/flow/changes/${changeId}/design`),
+
+  getSpec: (changeId: string) =>
+    api.get<{ changeId: string; content: string | null; specId: string | null }>(`/api/flow/changes/${changeId}/spec`),
+
+  getSpecById: (changeId: string, specId: string) =>
+    api.get<{ specId: string; content: string | null; location: string | null }>(
+      `/api/flow/changes/${changeId}/specs/${specId}`
+    ),
+
+  listTasks: (params?: { changeId?: string; stage?: string; status?: string; standalone?: boolean; includeArchived?: boolean }) => {
+    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: unknown[] }>(`/api/flow/tasks${query ? `?${query}` : ''}`)
+  },
+
+  createTask: (data: { changeId?: string; stage?: string; title: string; description?: string; priority?: string }) =>
+    api.post<{ task: unknown }>('/api/flow/tasks', data),
+
+  updateTask: (taskId: string, data: Record<string, unknown>) =>
+    api.patch<{ task: unknown }>(`/api/flow/tasks/${taskId}`, data),
+}
+
+export const tasksApi = {
+  list: (params?: { status?: string; priority?: string; tags?: string; kanban?: boolean }) => {
+    const searchParams = new URLSearchParams()
+    if (params?.status) searchParams.set('status', params.status)
+    if (params?.priority) searchParams.set('priority', params.priority)
+    if (params?.tags) searchParams.set('tags', params.tags)
+    if (params?.kanban) searchParams.set('kanban', 'true')
+    const query = searchParams.toString()
+    return api.get<unknown>(`/api/tasks${query ? `?${query}` : ''}`)
+  },
+
+  listArchived: (params?: { page?: number; limit?: number; search?: string }) => {
+    const searchParams = new URLSearchParams()
+    if (params?.page) searchParams.set('page', params.page.toString())
+    if (params?.limit) searchParams.set('limit', params.limit.toString())
+    if (params?.search) searchParams.set('search', params.search)
+    const query = searchParams.toString()
+    return api.get<unknown>(`/api/tasks/archived${query ? `?${query}` : ''}`)
+  },
+
+  get: (taskId: string) => api.get<unknown>(`/api/tasks/${taskId}`),
+
+  create: (data: Record<string, unknown>) => api.post<{ task: unknown }>('/api/tasks', data),
+
+  update: (taskId: string, data: Record<string, unknown>) => api.patch<{ task: unknown }>(`/api/tasks/${taskId}`, data),
+
+  delete: (taskId: string) => api.delete<void>(`/api/tasks/${taskId}`),
+
+  archive: (taskId: string) => api.post<{ task: unknown }>(`/api/tasks/${taskId}/archive`),
+
+  unarchive: (taskId: string) => api.post<{ task: unknown }>(`/api/tasks/${taskId}/unarchive`),
+
+  search: (query: string) => api.get<{ tasks: unknown[] }>(`/api/tasks/search?q=${encodeURIComponent(query)}`),
+}
+
+export const healthApi = {
+  check: () => api.get<{ status: string; timestamp: string; uptime: number }>('/api/health'),
+}
+
+// =============================================
+// Export error classes for use throughout the app
+// =============================================
+export { ApiError, TimeoutError, NetworkError, ValidationError, isApiError, isTimeoutError, isNetworkError, isValidationError, getErrorMessage, getErrorCode } from './errors'
+
+export default api

package/src/api/error-interceptor.ts

@@ -0,0 +1,366 @@
+/**
+ * API Error Interceptor
+ *
+ * Handles request/response interception, error classification,
+ * retry logic, and logging with sensitive data filtering
+ *
+ * @module api/error-interceptor
+ */
+
+import { withRetry, RetryOptions } from './retry-logic'
+import { getErrorLogger } from '@/utils/error-logger'
+import { useErrorStore_addError } from '@/stores/errorStore'
+import { ApiError, TimeoutError, NetworkError } from './errors'
+import { ErrorContext, ErrorSeverity, ErrorType } from '@/types/errors'
+
+// =============================================
+// Types
+// =============================================
+
+export interface RequestContext {
+  url: string
+  method: string
+  headers?: Record<string, string>
+  body?: unknown
+  timestamp: number
+}
+
+export interface ResponseContext {
+  status: number
+  statusText: string
+  headers?: Record<string, string>
+  body?: unknown
+  timestamp: number
+  duration: number
+}
+
+export interface InterceptorOptions {
+  /** Enable request logging (default: true) */
+  logRequests?: boolean
+  /** Enable response logging (default: true) */
+  logResponses?: boolean
+  /** Enable error logging to store (default: true) */
+  logToStore?: boolean
+  /** Retry options */
+  retry?: RetryOptions
+  /** Sensitive headers to redact (default: ['authorization', 'x-api-key']) */
+  sensitiveHeaders?: string[]
+  /** Sensitive body fields to redact (default: ['password', 'token', 'apiKey', 'secret']) */
+  sensitiveBodyFields?: string[]
+}
+
+// =============================================
+// Default Configuration
+// =============================================
+
+const DEFAULT_SENSITIVE_HEADERS = ['authorization', 'x-api-key', 'cookie']
+const DEFAULT_SENSITIVE_BODY_FIELDS = ['password', 'token', 'apiKey', 'secret', 'accessToken']
+
+// =============================================
+// Sensitive Data Filtering
+// =============================================
+
+/**
+ * Redact sensitive headers
+ */
+function redactHeaders(
+  headers?: Record<string, string>,
+  sensitiveHeaders: string[] = DEFAULT_SENSITIVE_HEADERS
+): Record<string, string> {
+  if (!headers) return {}
+
+  const redacted = { ...headers }
+  const lowerSensitiveHeaders = sensitiveHeaders.map((h) => h.toLowerCase())
+
+  Object.keys(redacted).forEach((key) => {
+    if (lowerSensitiveHeaders.includes(key.toLowerCase())) {
+      redacted[key] = '[REDACTED]'
+    }
+  })
+
+  return redacted
+}
+
+/**
+ * Redact sensitive fields in object
+ */
+function redactObjectFields(
+  obj: unknown,
+  sensitiveFields: string[] = DEFAULT_SENSITIVE_BODY_FIELDS
+): unknown {
+  if (obj === null || obj === undefined) return obj
+  if (typeof obj !== 'object') return obj
+
+  const lowerSensitiveFields = sensitiveFields.map((f) => f.toLowerCase())
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => redactObjectFields(item, sensitiveFields))
+  }
+
+  const redacted = { ...obj }
+  Object.keys(redacted).forEach((key) => {
+    const lowerKey = key.toLowerCase()
+    if (lowerSensitiveFields.includes(lowerKey)) {
+      redacted[key] = '[REDACTED]'
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactObjectFields(redacted[key], sensitiveFields)
+    }
+  })
+
+  return redacted
+}
+
+/**
+ * Create safe version of request context for logging
+ */
+function createSafeRequestContext(
+  context: RequestContext,
+  options: InterceptorOptions = {}
+): RequestContext {
+  const { sensitiveHeaders = DEFAULT_SENSITIVE_HEADERS, sensitiveBodyFields = DEFAULT_SENSITIVE_BODY_FIELDS } = options
+
+  return {
+    ...context,
+    headers: redactHeaders(context.headers, sensitiveHeaders),
+    body: redactObjectFields(context.body, sensitiveBodyFields),
+  }
+}
+
+/**
+ * Classify HTTP error based on status code
+ */
+function classifyHttpError(status: number): { type: ErrorType; severity: ErrorSeverity } {
+  if (status >= 400 && status < 500) {
+    // 4xx errors are validation errors
+    if (status === 401 || status === 403) {
+      return { type: 'NetworkError', severity: ErrorSeverity.ERROR }
+    }
+    return { type: 'ValidationError', severity: ErrorSeverity.WARNING }
+  }
+
+  if (status >= 500) {
+    // 5xx errors are server errors
+    return { type: 'NetworkError', severity: ErrorSeverity.ERROR }
+  }
+
+  return { type: 'NetworkError', severity: ErrorSeverity.WARNING }
+}
+
+/**
+ * Create error context from API error
+ */
+function createErrorContextFromApiError(
+  error: ApiError,
+  requestContext: RequestContext,
+  responseContext?: ResponseContext
+): ErrorContext {
+  const { type, severity } = classifyHttpError(error.status)
+
+  return {
+    code: error.code || `ERR_HTTP_${error.status}`,
+    message: error.message,
+    type,
+    severity,
+    timestamp: Date.now(),
+    userAction: `API call to ${requestContext.method} ${requestContext.url}`,
+    recoverable: error.status < 500 || error.status === 503 || error.status === 502,
+    suggestedActions: [
+      error.status < 500 ? 'Check input parameters and try again' : 'Try again after a moment',
+    ],
+    isDevelopment: false,
+  }
+}
+
+/**
+ * Create error context from timeout error
+ */
+function createErrorContextFromTimeoutError(
+  error: TimeoutError,
+  requestContext: RequestContext
+): ErrorContext {
+  return {
+    code: 'ERR_REQUEST_TIMEOUT',
+    message: `Request timeout: ${requestContext.method} ${requestContext.url}`,
+    type: 'NetworkError',
+    severity: ErrorSeverity.WARNING,
+    timestamp: Date.now(),
+    userAction: `API call to ${requestContext.method} ${requestContext.url}`,
+    recoverable: true,
+    suggestedActions: ['Retry the request', 'Check your network connection'],
+    isDevelopment: false,
+  }
+}
+
+/**
+ * Create error context from network error
+ */
+function createErrorContextFromNetworkError(
+  error: NetworkError,
+  requestContext: RequestContext
+): ErrorContext {
+  return {
+    code: 'ERR_NETWORK',
+    message: `Network error: ${error.message}`,
+    type: 'NetworkError',
+    severity: ErrorSeverity.ERROR,
+    timestamp: Date.now(),
+    userAction: `API call to ${requestContext.method} ${requestContext.url}`,
+    recoverable: true,
+    suggestedActions: ['Check your internet connection', 'Retry the request'],
+    isDevelopment: false,
+  }
+}
+
+// =============================================
+// Interceptor Implementation
+// =============================================
+
+export class RequestInterceptor {
+  private options: InterceptorOptions
+
+  constructor(options: InterceptorOptions = {}) {
+    this.options = {
+      logRequests: options.logRequests !== false,
+      logResponses: options.logResponses !== false,
+      logToStore: options.logToStore !== false,
+      sensitiveHeaders: options.sensitiveHeaders ?? DEFAULT_SENSITIVE_HEADERS,
+      sensitiveBodyFields: options.sensitiveBodyFields ?? DEFAULT_SENSITIVE_BODY_FIELDS,
+      ...options,
+    }
+  }
+
+  /**
+   * Log request (with sensitive data filtering)
+   */
+  private logRequest(context: RequestContext): void {
+    if (!this.options.logRequests) return
+
+    const safeContext = createSafeRequestContext(context, this.options)
+    getErrorLogger().log({
+      code: 'API_REQUEST',
+      message: `${context.method} ${context.url}`,
+      type: 'NetworkError',
+      severity: ErrorSeverity.INFO,
+      timestamp: context.timestamp,
+      userAction: `API call to ${context.method} ${context.url}`,
+      recoverable: false,
+      suggestedActions: [],
+      isDevelopment: false,
+      requestData: safeContext,
+    })
+  }
+
+  /**
+   * Log response (with sensitive data filtering)
+   */
+  private logResponse(
+    requestContext: RequestContext,
+    responseContext: ResponseContext
+  ): void {
+    if (!this.options.logResponses) return
+
+    const safeRequestContext = createSafeRequestContext(requestContext, this.options)
+    getErrorLogger().log({
+      code: `API_RESPONSE_${responseContext.status}`,
+      message: `${responseContext.status} ${responseContext.statusText} - ${requestContext.method} ${requestContext.url}`,
+      type: 'NetworkError',
+      severity: ErrorSeverity.INFO,
+      timestamp: responseContext.timestamp,
+      userAction: `API call to ${requestContext.method} ${requestContext.url}`,
+      recoverable: false,
+      suggestedActions: [],
+      isDevelopment: false,
+      requestData: safeRequestContext,
+    })
+  }
+
+  /**
+   * Log error to store
+   */
+  private logErrorToStore(errorContext: ErrorContext): void {
+    if (!this.options.logToStore) return
+
+    try {
+      useErrorStore_addError(errorContext)
+    } catch (error) {
+      // Silently fail if store is not available
+      console.warn('Failed to log error to store', error)
+    }
+  }
+
+  /**
+   * Intercept and handle API request with retry logic
+   */
+  async intercept<T>(
+    requestFn: () => Promise<T>,
+    requestContext: RequestContext
+  ): Promise<T> {
+    // Log request
+    this.logRequest(requestContext)
+
+    // Execute with retry logic
+    const retryOptions = this.options.retry
+    return withRetry(requestFn, retryOptions)
+  }
+
+  /**
+   * Handle API error with logging and store
+   */
+  handleError(error: unknown, requestContext: RequestContext): void {
+    let errorContext: ErrorContext | null = null
+
+    if (error instanceof ApiError) {
+      errorContext = createErrorContextFromApiError(error, requestContext)
+    } else if (error instanceof TimeoutError) {
+      errorContext = createErrorContextFromTimeoutError(error, requestContext)
+    } else if (error instanceof NetworkError) {
+      errorContext = createErrorContextFromNetworkError(error, requestContext)
+    } else if (error instanceof Error) {
+      errorContext = {
+        code: 'ERR_UNKNOWN',
+        message: error.message,
+        type: 'NetworkError',
+        severity: ErrorSeverity.ERROR,
+        timestamp: Date.now(),
+        userAction: `API call to ${requestContext.method} ${requestContext.url}`,
+        recoverable: true,
+        suggestedActions: ['Refresh the page', 'Try again later'],
+        isDevelopment: false,
+      }
+    }
+
+    if (errorContext) {
+      this.logErrorToStore(errorContext)
+      getErrorLogger().log(errorContext)
+    }
+  }
+}
+
+// =============================================
+// Singleton Instance
+// =============================================
+
+let interceptorInstance: RequestInterceptor | null = null
+
+export function getRequestInterceptor(
+  options?: InterceptorOptions
+): RequestInterceptor {
+  if (!interceptorInstance) {
+    interceptorInstance = new RequestInterceptor(options)
+  }
+  return interceptorInstance
+}
+
+/**
+ * Configure global request interceptor
+ */
+export function configureInterceptor(options: InterceptorOptions): void {
+  interceptorInstance = new RequestInterceptor(options)
+}
+
+/**
+ * Reset interceptor to default configuration
+ */
+export function resetInterceptor(): void {
+  interceptorInstance = null
+}