@codeguide/core 0.0.28 → 0.0.33

package/services/base/base-service.ts

@@ -238,6 +238,11 @@ export abstract class BaseService {
     return response.data
   }
 
+  protected async patch<T>(url: string, data?: any, config?: any): Promise<T> {
+    const response = await this.client.patch<T>(url, data, config)
+    return response.data
+  }
+
   protected async delete<T>(url: string, config?: any): Promise<T> {
     const response = await this.client.delete<T>(url, config)
     return response.data
@@ -246,4 +251,129 @@ export abstract class BaseService {
   protected buildUrl(endpoint: string): string {
     return endpoint.startsWith('/') ? endpoint : `/${endpoint}`
   }
+
+  /**
+   * Create a streaming connection for Server-Sent Events (SSE)
+   *
+   * @param url - The endpoint URL for streaming
+   * @param config - Optional configuration for the stream request
+   * @returns Promise that resolves to EventSource for SSE streaming
+   */
+  protected async createStream(url: string, config?: any): Promise<EventSource> {
+    // Build full URL
+    const fullUrl = `${this.client.defaults.baseURL}${this.buildUrl(url)}`
+
+    // For SSE, we need to use EventSource API directly
+    // However, we need to handle authentication differently since EventSource doesn't support custom headers
+    // We'll pass auth info as query parameters for SSE endpoints
+
+    return new Promise((resolve, reject) => {
+      try {
+        const eventSource = new EventSource(fullUrl)
+        resolve(eventSource)
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Alternative streaming method using fetch for environments where EventSource is not available
+   * or when custom headers are needed for authentication
+   *
+   * @param url - The endpoint URL for streaming
+   * @param onMessage - Callback function for handling stream messages
+   * @param onError - Callback function for handling stream errors
+   * @param onComplete - Callback function for when stream completes
+   * @param config - Optional configuration for the stream request
+   * @returns Promise that resolves to a cleanup function
+   */
+  protected async createStreamWithFetch(
+    url: string,
+    onMessage: (data: any) => void,
+    onError?: (error: any) => void,
+    onComplete?: () => void,
+    config?: any
+  ): Promise<() => void> {
+    const streamConfig = {
+      ...config,
+      headers: {
+        ...this.client.defaults.headers,
+        'Accept': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        ...config?.headers,
+      },
+    }
+
+    const fullUrl = `${this.client.defaults.baseURL}${this.buildUrl(url)}`
+
+    try {
+      const response = await fetch(fullUrl, streamConfig)
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+      }
+
+      const reader = response.body?.getReader()
+      if (!reader) {
+        throw new Error('Response body is not readable')
+      }
+
+      const decoder = new TextDecoder()
+      let buffer = ''
+
+      const processStream = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read()
+
+            if (done) {
+              onComplete?.()
+              break
+            }
+
+            buffer += decoder.decode(value, { stream: true })
+            const lines = buffer.split('\n')
+            buffer = lines.pop() || '' // Keep incomplete line in buffer
+
+            for (const line of lines) {
+              if (line.startsWith('data: ')) {
+                const data = line.slice(6) // Remove 'data: ' prefix
+                if (data.trim()) {
+                  try {
+                    const parsedData = JSON.parse(data)
+                    onMessage(parsedData)
+                  } catch (parseError) {
+                    console.warn('Failed to parse SSE data:', data, parseError)
+                  }
+                }
+              } else if (line.startsWith('event: ')) {
+                const eventType = line.slice(7) // Remove 'event: ' prefix
+                // Handle different event types if needed
+                if (eventType === 'complete') {
+                  onComplete?.()
+                  return
+                } else if (eventType === 'error') {
+                  onError?.(new Error('Stream error event received'))
+                  return
+                }
+              }
+            }
+          }
+        } catch (error) {
+          onError?.(error)
+        }
+      }
+
+      processStream()
+
+      // Return cleanup function
+      return () => {
+        reader.cancel().catch(console.warn)
+      }
+    } catch (error) {
+      onError?.(error)
+      return () => {} // Return empty cleanup function on error
+    }
+  }
 }

package/services/codespace/codespace-service.ts

@@ -22,6 +22,23 @@ import {
   GetLLMModelProvidersResponse,
   GetLLMModelProviderResponse,
   GetModelsByProviderResponse,
+  // GET /codespace/tasks Types
+  GetCodespaceTasksRequest,
+  GetCodespaceTasksResponse,
+  // GET /tasks/by-codespace-id Types
+  GetTasksByCodespaceIdRequest,
+  GetTasksByCodespaceIdResponse,
+  // Final Report Popup State Types
+  UpdateFinalReportPopupStateRequest,
+  UpdateFinalReportPopupStateResponse,
+  // Codespace Task Logs Types
+  GetCodespaceTaskLogsRequest,
+  CodespaceTaskLogsResponse,
+  StreamCodespaceTaskLogsRequest,
+  CodespaceLogStreamEvent,
+  // Project Summary Types
+  GetCodespaceProjectSummaryRequest,
+  GetCodespaceProjectSummaryResponse,
 } from './codespace-types'
 
 export class CodespaceService extends BaseService {
@@ -93,6 +110,25 @@ export class CodespaceService extends BaseService {
     return this.get<GetCodespaceTasksByProjectResponse>(url)
   }
 
+  /**
+   * Get aggregated statistics for all codespace tasks within a project
+   *
+   * GET /codespace/project/{project_id}/summary
+   *
+   * @param params - Request parameters including project_id
+   * @returns Promise resolving to aggregated task statistics by status
+   */
+  async getCodespaceProjectSummary(
+    params: GetCodespaceProjectSummaryRequest
+  ): Promise<GetCodespaceProjectSummaryResponse> {
+    if (!params.project_id) {
+      throw new Error('project_id is required')
+    }
+
+    const url = `/codespace/project/${params.project_id}/summary`
+    return this.get<GetCodespaceProjectSummaryResponse>(url)
+  }
+
   async getCodespaceTaskDetailed(codespaceTaskId: string): Promise<CodespaceTaskDetailedResponse> {
     if (!codespaceTaskId) {
       throw new Error('codespace_task_id is required')
@@ -100,6 +136,216 @@ export class CodespaceService extends BaseService {
     return this.get<CodespaceTaskDetailedResponse>(`/codespace/task/${codespaceTaskId}/detailed`)
   }
 
+  /**
+   * Get tasks by codespace task ID with optional pagination and sorting
+   *
+   * GET /tasks/by-codespace-id/{codespace_task_id}
+   *
+   * @param params - Request parameters including codespace_task_id and optional pagination/sorting
+   * @returns Promise resolving to paginated list of tasks associated with the codespace task ID
+   */
+  async getTasksByCodespaceId(
+    params: GetTasksByCodespaceIdRequest
+  ): Promise<GetTasksByCodespaceIdResponse> {
+    this.validateGetTasksByCodespaceIdRequest(params)
+
+    const queryParams = new URLSearchParams()
+
+    // Add pagination parameters
+    if (params.limit !== undefined) {
+      queryParams.append('limit', params.limit.toString())
+    }
+    if (params.offset !== undefined) {
+      queryParams.append('offset', params.offset.toString())
+    }
+
+    // Add sorting parameters
+    if (params.sort_by) {
+      queryParams.append('sort_by', params.sort_by)
+    }
+    if (params.sort_order) {
+      queryParams.append('sort_order', params.sort_order)
+    }
+
+    const url = `/codespace/tasks/by-codespace-id/${params.codespace_task_id}${
+      queryParams.toString() ? `?${queryParams.toString()}` : ''
+    }`
+
+    return this.get<GetTasksByCodespaceIdResponse>(url)
+  }
+
+  /**
+   * Get codespace tasks with optional filtering and pagination
+   *
+   * GET /codespace/tasks
+   *
+   * @param params - Optional query parameters for filtering, sorting, and pagination
+   * @returns Promise resolving to paginated list of codespace tasks with model and attachment info
+   */
+  async getCodespaceTasks(params?: GetCodespaceTasksRequest): Promise<GetCodespaceTasksResponse> {
+    const queryParams = new URLSearchParams()
+
+    if (params?.task_status) queryParams.append('task_status', params.task_status)
+    if (params?.project_id) queryParams.append('project_id', params.project_id)
+    if (params?.limit !== undefined) {
+      // Validate limit is between 1 and 100
+      if (params.limit < 1 || params.limit > 100) {
+        throw new Error('limit must be between 1 and 100')
+      }
+      queryParams.append('limit', params.limit.toString())
+    }
+    if (params?.offset !== undefined) {
+      // Validate offset is non-negative
+      if (params.offset < 0) {
+        throw new Error('offset must be 0 or greater')
+      }
+      queryParams.append('offset', params.offset.toString())
+    }
+    if (params?.sort_by) queryParams.append('sort_by', params.sort_by)
+    if (params?.sort_order) queryParams.append('sort_order', params.sort_order)
+
+    const url = `/codespace/tasks${queryParams.toString() ? `?${queryParams.toString()}` : ''}`
+    return this.get<GetCodespaceTasksResponse>(url)
+  }
+
+  // ============================================================================
+  // Task Status Update Methods
+  // ============================================================================
+
+  /**
+   * Update the final report popup state for a codespace task
+   *
+   * PATCH /codespace/task/{codespace_task_id}/final-report-popup-state
+   *
+   * @param codespaceTaskId - The ID of the codespace task
+   * @param request - The request body containing the new popup state
+   * @returns Promise resolving to the updated popup state response
+   */
+  async updateFinalReportPopupState(
+    codespaceTaskId: string,
+    request: UpdateFinalReportPopupStateRequest
+  ): Promise<UpdateFinalReportPopupStateResponse> {
+    if (!codespaceTaskId) {
+      throw new Error('codespace_task_id is required')
+    }
+
+    // Validate the popup state value
+    if (!['not_ready', 'open', 'closed'].includes(request.final_report_popup_state)) {
+      throw new Error('final_report_popup_state must be "not_ready", "open", or "closed"')
+    }
+
+    return this.patch<UpdateFinalReportPopupStateResponse>(
+      `/codespace/task/${codespaceTaskId}/final-report-popup-state`,
+      request
+    )
+  }
+
+  // ============================================================================
+  // Codespace Task Logs Methods
+  // ============================================================================
+
+  /**
+   * Get paginated logs for a codespace task with optional filtering and sorting
+   *
+   * GET /codespace/task/{codespace_task_id}/logs
+   *
+   * @param request - Request parameters including codespace_task_id and optional filters
+   * @returns Promise resolving to paginated logs response
+   */
+  async getCodespaceTaskLogs(
+    request: GetCodespaceTaskLogsRequest
+  ): Promise<CodespaceTaskLogsResponse> {
+    this.validateGetLogsRequest(request)
+
+    const queryParams = new URLSearchParams()
+
+    // Add pagination parameters
+    if (request.limit !== undefined) {
+      queryParams.append('limit', request.limit.toString())
+    }
+    if (request.offset !== undefined) {
+      queryParams.append('offset', request.offset.toString())
+    }
+
+    // Add filter parameters
+    if (request.log_type) {
+      queryParams.append('log_type', request.log_type)
+    }
+    if (request.step_name) {
+      queryParams.append('step_name', request.step_name)
+    }
+    if (request.search) {
+      queryParams.append('search', request.search)
+    }
+    if (request.since) {
+      queryParams.append('since', request.since)
+    }
+
+    // Add sorting parameters
+    if (request.sort_by) {
+      queryParams.append('sort_by', request.sort_by)
+    }
+    if (request.sort_order) {
+      queryParams.append('sort_order', request.sort_order)
+    }
+
+    const url = `/codespace/task/${request.codespace_task_id}/logs${
+      queryParams.toString() ? `?${queryParams.toString()}` : ''
+    }`
+
+    return this.get<CodespaceTaskLogsResponse>(url)
+  }
+
+  /**
+   * Stream real-time logs from a codespace task using Server-Sent Events (SSE)
+   *
+   * GET /codespace/task/{codespace_task_id}/logs/stream
+   *
+   * @param request - Request parameters including codespace_task_id and optional streaming parameters
+   * @param onLog - Callback function for handling log events
+   * @param onHeartbeat - Callback function for handling heartbeat events
+   * @param onComplete - Callback function for handling completion events
+   * @param onError - Callback function for handling error events
+   * @param onTimeout - Callback function for handling timeout events
+   * @returns Promise resolving to a cleanup function to stop streaming
+   */
+  async streamCodespaceTaskLogs(
+    request: StreamCodespaceTaskLogsRequest,
+    onLog: (log: CodespaceLogStreamEvent) => void,
+    onHeartbeat?: (data: any) => void,
+    onComplete?: (data: any) => void,
+    onError?: (error: any) => void,
+    onTimeout?: (data: any) => void
+  ): Promise<() => void> {
+    this.validateStreamLogsRequest(request)
+
+    const queryParams = new URLSearchParams()
+
+    // Add streaming parameters
+    if (request.since) {
+      queryParams.append('since', request.since)
+    }
+    if (request.timeout !== undefined) {
+      queryParams.append('timeout', request.timeout.toString())
+    }
+
+    const url = `/codespace/task/${request.codespace_task_id}/logs/stream${
+      queryParams.toString() ? `?${queryParams.toString()}` : ''
+    }`
+
+    // Use the fetch-based streaming method since it supports custom headers for authentication
+    return this.createStreamWithFetch(
+      url,
+      data => {
+        // Handle different types of events based on the context
+        // The server will send different event types through the same data channel
+        onLog(data as CodespaceLogStreamEvent)
+      },
+      onError,
+      () => onComplete?.({}) // Call onComplete with empty data when stream completes
+    )
+  }
+
   // ============================================================================
   // Codespace Models Methods
   // ============================================================================
@@ -285,4 +531,117 @@ export class CodespaceService extends BaseService {
       }
     }
   }
+
+  private validateGetLogsRequest(request: GetCodespaceTaskLogsRequest): void {
+    if (!request.codespace_task_id) {
+      throw new Error('codespace_task_id is required')
+    }
+
+    // Validate limit
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit)) {
+        throw new Error('limit must be an integer')
+      }
+      if (request.limit < 1 || request.limit > 500) {
+        throw new Error('limit must be between 1 and 500')
+      }
+    }
+
+    // Validate offset
+    if (request.offset !== undefined) {
+      if (!Number.isInteger(request.offset)) {
+        throw new Error('offset must be an integer')
+      }
+      if (request.offset < 0) {
+        throw new Error('offset must be 0 or greater')
+      }
+    }
+
+    // Validate sort_by
+    if (request.sort_by && !['created_at', 'step_name', 'log_type'].includes(request.sort_by)) {
+      throw new Error('sort_by must be one of: created_at, step_name, log_type')
+    }
+
+    // Validate sort_order
+    if (request.sort_order && !['asc', 'desc'].includes(request.sort_order)) {
+      throw new Error('sort_order must be either "asc" or "desc"')
+    }
+
+    // Validate log_type
+    const validLogTypes = ['thinking', 'coding', 'info', 'error', 'success']
+    if (request.log_type && !validLogTypes.includes(request.log_type)) {
+      throw new Error(`log_type must be one of: ${validLogTypes.join(', ')}`)
+    }
+
+    // Validate since timestamp format (basic ISO format check)
+    if (request.since) {
+      const sinceDate = new Date(request.since)
+      if (isNaN(sinceDate.getTime())) {
+        throw new Error('since must be a valid ISO timestamp')
+      }
+    }
+  }
+
+  private validateStreamLogsRequest(request: StreamCodespaceTaskLogsRequest): void {
+    if (!request.codespace_task_id) {
+      throw new Error('codespace_task_id is required')
+    }
+
+    // Validate timeout
+    if (request.timeout !== undefined) {
+      if (!Number.isInteger(request.timeout)) {
+        throw new Error('timeout must be an integer')
+      }
+      if (request.timeout < 30 || request.timeout > 1800) {
+        throw new Error('timeout must be between 30 and 1800 seconds')
+      }
+    }
+
+    // Validate since timestamp format (basic ISO format check)
+    if (request.since) {
+      const sinceDate = new Date(request.since)
+      if (isNaN(sinceDate.getTime())) {
+        throw new Error('since must be a valid ISO timestamp')
+      }
+    }
+  }
+
+  private validateGetTasksByCodespaceIdRequest(request: GetTasksByCodespaceIdRequest): void {
+    if (!request.codespace_task_id) {
+      throw new Error('codespace_task_id is required')
+    }
+
+    // Validate limit
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit)) {
+        throw new Error('limit must be an integer')
+      }
+      if (request.limit < 1 || request.limit > 100) {
+        throw new Error('limit must be between 1 and 100')
+      }
+    }
+
+    // Validate offset
+    if (request.offset !== undefined) {
+      if (!Number.isInteger(request.offset)) {
+        throw new Error('offset must be an integer')
+      }
+      if (request.offset < 0) {
+        throw new Error('offset must be 0 or greater')
+      }
+    }
+
+    // Validate sort_by
+    if (
+      request.sort_by &&
+      !['created_at', 'updated_at', 'status', 'title'].includes(request.sort_by)
+    ) {
+      throw new Error('sort_by must be one of: created_at, updated_at, status, title')
+    }
+
+    // Validate sort_order
+    if (request.sort_order && !['asc', 'desc'].includes(request.sort_order)) {
+      throw new Error('sort_order must be either "asc" or "desc"')
+    }
+  }
 }