@codeguide/core 0.0.28 → 0.0.29

package/docs/usage-service.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Usage Service provides methods to track usage, check credits, and retrieve authorization information for users.
+The Usage Service provides methods to track usage, check credits, retrieve authorization information, and access comprehensive dashboard analytics for users.
 
 ## Methods
 
@@ -324,3 +324,293 @@ interface PlanLimits {
   }
 }
 ```
+
+# Dashboard Analytics
+
+The Usage Service also provides comprehensive dashboard analytics endpoints for visualizing usage patterns, costs, and trends. All dashboard endpoints follow the `/usage/dashboard/*` pattern.
+
+## `getDashboardAnalytics(params?)`
+
+Retrieves comprehensive analytics data with daily breakdowns, trends, and top services for dashboard visualization.
+
+**Endpoint:** `GET /usage/dashboard/analytics`
+
+**Parameters:** `DashboardAnalyticsRequest` (optional)
+```typescript
+interface DashboardAnalyticsRequest {
+  period?: "7d" | "1w" | "1m" | "3m"    // Time period
+  start_date?: string                    // Custom start date (YYYY-MM-DD)
+  end_date?: string                      // Custom end date (YYYY-MM-DD)
+  service_type?: "docs" | "chat" | "codespace_task" | "api"
+}
+```
+
+**Returns:** `Promise<DashboardAnalyticsResponse>`
+
+**Response Structure:**
+```typescript
+interface DashboardAnalyticsResponse {
+  status: string
+  data: {
+    period: {
+      start: string
+      end: string
+      label: string
+    }
+    daily_usage: Array<{
+      date: string
+      credits_consumed: number
+      cost_usd: number
+      requests_count: number
+      average_credits_per_request: number
+    }>
+    totals: {
+      credits_consumed: number
+      cost_usd: number
+      requests_count: number
+    }
+    averages: {
+      daily_credits: number
+      daily_requests: number
+    }
+    trends: {
+      credits_consumed: number      // Percentage change
+      requests_count: number        // Percentage change
+    }
+    top_services: Array<{
+      service_type: string
+      credits_consumed: number
+      requests_count: number
+    }>
+  }
+}
+```
+
+**Example Usage:**
+```typescript
+// Get last 7 days analytics
+const analytics = await codeguide.usage.getDashboardAnalytics({ period: '7d' })
+
+// Get custom date range for docs service
+const docsAnalytics = await codeguide.usage.getDashboardAnalytics({
+  start_date: '2024-01-01',
+  end_date: '2024-01-31',
+  service_type: 'docs'
+})
+```
+
+## `getUsageDetails(params?)`
+
+Retrieves paginated individual usage records with filtering and sorting capabilities for detailed analysis.
+
+**Endpoint:** `GET /usage/dashboard/details`
+
+**Parameters:** `UsageDetailsRequest` (optional)
+```typescript
+interface UsageDetailsRequest {
+  period?: "7d" | "1w" | "1m" | "3m"
+  start_date?: string
+  end_date?: string
+  service_type?: "docs" | "chat" | "codespace_task" | "api"
+  page?: number                         // Default: 1
+  page_size?: number                    // Default: 50, Max: 100
+  sort_by?: "created_at" | "credits_consumed" | "cost_amount"  // Default: "created_at"
+  sort_order?: "asc" | "desc"           // Default: "desc"
+}
+```
+
+**Returns:** `Promise<UsageDetailsResponse>`
+
+**Response Structure:**
+```typescript
+interface UsageDetailsResponse {
+  status: string
+  data: Array<{
+    id: string
+    created_at: string
+    service_type: string
+    model_name: string
+    usage_type: string
+    units_consumed: number
+    credits_consumed: number
+    cost_amount: number | null
+  }>
+  pagination: {
+    page: number
+    page_size: number
+    total_count: number
+    total_pages: number
+    has_next: boolean
+    has_prev: boolean
+  }
+  filters: {
+    period: string | null
+    start_date: string | null
+    end_date: string | null
+    service_type: string | null
+  }
+}
+```
+
+**Example Usage:**
+```typescript
+// Get first page of usage details for last 7 days
+const details = await codeguide.usage.getUsageDetails({ period: '7d' })
+
+// Get page 2 with custom sorting
+const sortedDetails = await codeguide.usage.getUsageDetails({
+  period: '1m',
+  page: 2,
+  page_size: 25,
+  sort_by: 'credits_consumed',
+  sort_order: 'desc'
+})
+```
+
+## `getUsageSummary(params?)`
+
+Retrieves quick overview statistics for dashboard widgets, including current vs previous period comparisons and billing cycle information.
+
+**Endpoint:** `GET /usage/dashboard/summary`
+
+**Parameters:** `UsageSummaryRequest` (optional)
+```typescript
+interface UsageSummaryRequest {
+  period?: "7d" | "1w" | "1m" | "3m"
+  start_date?: string
+  end_date?: string
+}
+```
+
+**Returns:** `Promise<UsageSummaryResponse>`
+
+**Response Structure:**
+```typescript
+interface UsageSummaryResponse {
+  status: string
+  data: {
+    current_period: {
+      credits_consumed: number
+      cost_usd: number
+      requests_count: number
+    }
+    previous_period: {
+      credits_consumed: number
+      cost_usd: number
+      requests_count: number
+    }
+    billing_cycle: {
+      total_allotted: number
+      total_consumed: number
+      remaining_credits: number
+    }
+    utilization_percentage: number
+    remaining_credits: number
+    daily_average: number
+    projected_monthly: number
+  }
+}
+```
+
+**Example Usage:**
+```typescript
+// Get summary for last 7 days
+const summary = await codeguide.usage.getUsageSummary({ period: '7d' })
+
+// Get monthly summary
+const monthlySummary = await codeguide.usage.getUsageSummary({ period: '1m' })
+```
+
+## `getServiceBreakdown(params?)`
+
+Retrieves usage breakdown by service type for pie charts and comparative analysis.
+
+**Endpoint:** `GET /usage/dashboard/services`
+
+**Parameters:** `ServiceBreakdownRequest` (optional)
+```typescript
+interface ServiceBreakdownRequest {
+  period?: "7d" | "1w" | "1m" | "3m"
+  start_date?: string
+  end_date?: string
+}
+```
+
+**Returns:** `Promise<ServiceBreakdownResponse>`
+
+**Response Structure:**
+```typescript
+interface ServiceBreakdownResponse {
+  status: string
+  data: {
+    period: {
+      start: string
+      end: string
+      label: string
+    }
+    services: Array<{
+      service_type: string
+      credits_consumed: number
+      percentage: number
+      cost_usd: number
+      requests_count: number
+      trend: number           // Percentage change
+    }>
+    total_credits: number
+    total_cost: number
+  }
+}
+```
+
+**Example Usage:**
+```typescript
+// Get service breakdown for last 7 days
+const breakdown = await codeguide.usage.getServiceBreakdown({ period: '7d' })
+
+// Get service breakdown for custom date range
+const customBreakdown = await codeguide.usage.getServiceBreakdown({
+  start_date: '2024-01-01',
+  end_date: '2024-01-31'
+})
+```
+
+## Complete Dashboard Example
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.app',
+  databaseApiKey: 'sk_your_key',
+})
+
+// Get comprehensive dashboard data
+async function loadDashboardData() {
+  try {
+    // Main analytics with trends
+    const analytics = await codeguide.usage.getDashboardAnalytics({ period: '7d' })
+
+    // Quick overview for widgets
+    const summary = await codeguide.usage.getUsageSummary({ period: '7d' })
+
+    // Service breakdown for pie charts
+    const services = await codeguide.usage.getServiceBreakdown({ period: '7d' })
+
+    // Detailed records for table
+    const details = await codeguide.usage.getUsageDetails({
+      period: '7d',
+      page_size: 100,
+      sort_by: 'credits_consumed',
+      sort_order: 'desc'
+    })
+
+    console.log('Dashboard Analytics:', analytics.data)
+    console.log('Summary Stats:', summary.data)
+    console.log('Service Breakdown:', services.data)
+    console.log('Usage Details:', details.data)
+
+  } catch (error) {
+    console.error('Failed to load dashboard data:', error)
+  }
+}
+```

package/index.ts

@@ -18,7 +18,7 @@ export type {
   ProjectRepository,
   GetProjectsRequest,
   PaginatedProjectsRequest,
-  PaginatedProjectsResponse
+  PaginatedProjectsResponse,
 } from './services/projects/project-types'
 export type {
   CreateCodespaceTaskRequestV2 as CreateCodespaceTaskRequest,
@@ -30,7 +30,7 @@ export type {
   GetCodespaceTaskResponse,
   CodespaceTaskData,
   TechnicalDocument,
-  GetProjectTasksByCodespaceResponse
+  GetProjectTasksByCodespaceResponse,
 } from './services/codespace/codespace-types'
 
 // Export commonly used external tokens types for convenience
@@ -44,5 +44,13 @@ export type {
   FindBestMatchRequest,
   FindBestMatchResponse,
   Platform,
-  TokenType
+  TokenType,
 } from './services/external-tokens/external-tokens-types'
+
+// Export commonly used starter kits types for convenience
+export type {
+  StarterKit,
+  StarterKitMetadata,
+  GetStarterKitsRequest,
+  GetStarterKitsResponse,
+} from './services/starter-kits/starter-kits-types'

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "@codeguide/core",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "description": "Core package for code guidance with programmatic API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/services/starter-kits/starter-kits-types": {
+      "types": "./dist/services/starter-kits/starter-kits-types.d.ts"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "test": "jest --config=jest.config.json",
     "test:watch": "jest --config=jest.config.json --watch",
-    "test:coverage": "jest --config=jest.config.json --coverage"
+    "test:coverage": "jest --config=jest.config.json --coverage",
+    "docs:dev": "cd docs && npm run dev",
+    "docs:build": "cd docs && npm run build",
+    "docs:preview": "cd docs && npm run preview",
+    "docs:install": "cd docs && npm install",
+    "docs:setup": "npm run docs:install"
   },
   "keywords": [
     "api",

package/plans/CODESPACE_LOGS_STREAMING_GUIDE.md

@@ -0,0 +1,320 @@
+# Codespace Logs Streaming Guide
+
+## Overview
+The codespace logs API now supports real-time streaming using Server-Sent Events (SSE). This allows you to monitor logs from long-running codespace tasks in real-time.
+
+## Endpoints
+
+### 1. Standard REST API (Polling)
+```
+GET /codespace/task/{codespace_task_id}/logs
+```
+
+**Query Parameters:**
+- `limit` (1-500, default: 50) - Number of logs to return
+- `offset` (default: 0) - Pagination offset
+- `log_type` - Filter by type (thinking, coding, info, error, success)
+- `step_name` - Filter by step name (partial matching)
+- `search` - Search in message content
+- `sort_by` (created_at, step_name, log_type) - Sort field
+- `sort_order` (asc, desc) - Sort order
+- `since` - Get logs after timestamp (for incremental updates)
+
+### 2. Real-time Streaming (SSE) ⭐
+```
+GET /codespace/task/{codespace_task_id}/logs/stream
+```
+
+**Query Parameters:**
+- `since` (optional) - Start from timestamp (gets recent logs if not provided)
+- `timeout` (30-1800 seconds, default: 300) - Stream timeout
+
+## Client Implementation Examples
+
+### JavaScript/TypeScript (Recommended)
+
+```javascript
+// Basic streaming setup
+const taskLogsStream = (taskId) => {
+  const eventSource = new EventSource(
+    `/codespace/task/${taskId}/logs/stream`,
+    {
+      headers: {
+        'Authorization': `Bearer ${yourAuthToken}`
+      }
+    }
+  );
+
+  // Listen for new logs
+  eventSource.addEventListener('log', (event) => {
+    const log = JSON.parse(event.data);
+    console.log('New log:', log);
+
+    // Update UI
+    appendLogToTerminal(log);
+  });
+
+  // Listen for heartbeat (keep-alive)
+  eventSource.addEventListener('heartbeat', (event) => {
+    const data = JSON.parse(event.data);
+    console.log('Heartbeat:', data.timestamp);
+  });
+
+  // Listen for completion
+  eventSource.addEventListener('complete', (event) => {
+    console.log('Task completed!');
+    eventSource.close();
+    showCompletionMessage();
+  });
+
+  // Handle errors
+  eventSource.addEventListener('error', (event) => {
+    console.error('Stream error:', event);
+    eventSource.close();
+    showErrorMessage();
+  });
+
+  // Handle timeout
+  eventSource.addEventListener('timeout', (event) => {
+    console.log('Stream timeout, reconnecting...');
+    eventSource.close();
+    // Optionally reconnect with the 'since' parameter
+    reconnectWithTimestamp(taskId, lastTimestamp);
+  });
+
+  return eventSource;
+};
+
+// Usage
+const stream = taskLogsStream('your-codespace-task-id');
+
+// To stop streaming
+stream.close();
+```
+
+### React Hook Example
+
+```jsx
+import { useEffect, useState } from 'react';
+
+export const useCodespaceLogs = (taskId, authToken) => {
+  const [logs, setLogs] = useState([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    if (!taskId) return;
+
+    setIsStreaming(true);
+    setError(null);
+
+    const eventSource = new EventSource(
+      `/codespace/task/${taskId}/logs/stream`,
+      {
+        headers: {
+          'Authorization': `Bearer ${authToken}`
+        }
+      }
+    );
+
+    eventSource.addEventListener('log', (event) => {
+      const log = JSON.parse(event.data);
+      setLogs(prev => [...prev, log]);
+    });
+
+    eventSource.addEventListener('complete', () => {
+      setIsStreaming(false);
+      eventSource.close();
+    });
+
+    eventSource.addEventListener('error', () => {
+      setError('Failed to stream logs');
+      setIsStreaming(false);
+      eventSource.close();
+    });
+
+    return () => {
+      eventSource.close();
+    };
+  }, [taskId, authToken]);
+
+  return { logs, isStreaming, error };
+};
+
+// Usage in component
+function LogsViewer({ taskId, authToken }) {
+  const { logs, isStreaming, error } = useCodespaceLogs(taskId, authToken);
+
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <div className="logs-container">
+      <div className="status">
+        {isStreaming ? '🔄 Streaming...' : '✅ Complete'}
+      </div>
+      {logs.map(log => (
+        <div key={log.id} className={`log log-${log.log_type}`}>
+          <span className="timestamp">{log.created_at}</span>
+          <span className="step">{log.step_name}</span>
+          <span className="message">{log.message}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Python Example
+
+```python
+import requests
+import json
+from datetime import datetime
+
+def stream_codespace_logs(task_id, auth_token):
+    """Stream logs from a codespace task."""
+    url = f"http://localhost:8000/codespace/task/{task_id}/logs/stream"
+    headers = {
+        'Authorization': f'Bearer {auth_token}',
+        'Accept': 'text/event-stream'
+    }
+
+    try:
+        response = requests.get(url, headers=headers, stream=True)
+        response.raise_for_status()
+
+        for line in response.iter_lines():
+            if line:
+                line = line.decode('utf-8')
+
+                if line.startswith('data: '):
+                    data = json.loads(line[6:])
+                    print(f"[{datetime.now()}] {data}")
+                elif line.startswith('event: '):
+                    event_type = line[7:]
+                    print(f"Event: {event_type}")
+
+                    if event_type == 'complete':
+                        print("Task completed!")
+                        break
+                    elif event_type == 'error':
+                        print("Error occurred!")
+                        break
+
+    except requests.exceptions.RequestException as e:
+        print(f"Error streaming logs: {e}")
+
+# Usage
+stream_codespace_logs('your-task-id', 'your-auth-token')
+```
+
+### curl Example (for testing)
+
+```bash
+# Basic stream
+curl -N -H "Authorization: Bearer YOUR_TOKEN" \
+  "http://localhost:8000/codespace/task/TASK_ID/logs/stream"
+
+# With custom timeout
+curl -N -H "Authorization: Bearer YOUR_TOKEN" \
+  "http://localhost:8000/codespace/task/TASK_ID/logs/stream?timeout=600"
+
+# Start from specific timestamp
+curl -N -H "Authorization: Bearer YOUR_TOKEN" \
+  "http://localhost:8000/codespace/task/TASK_ID/logs/stream?since=2024-01-01T00:00:00Z"
+```
+
+## SSE Event Types
+
+### `log`
+```json
+{
+  "id": "uuid",
+  "step_name": "task_creation",
+  "log_type": "info",
+  "message": "🚀 Your coding task is ready!",
+  "created_at": "2024-01-01T00:00:00Z",
+  "progress_percentage": 25,
+  "metadata": {}
+}
+```
+
+### `heartbeat`
+```json
+{
+  "timestamp": "2024-01-01T00:00:00Z"
+}
+```
+
+### `complete`
+```json
+{
+  "message": "Task completed"
+}
+```
+
+### `timeout`
+```json
+{
+  "message": "Stream timeout reached"
+}
+```
+
+### `error`
+```json
+{
+  "error": "Error message"
+}
+```
+
+## Reconnection Strategy
+
+For production use, implement automatic reconnection:
+
+```javascript
+const connectWithRetry = (taskId, maxRetries = 5) => {
+  let retryCount = 0;
+
+  const connect = () => {
+    const eventSource = new EventSource(`/codespace/task/${taskId}/logs/stream`);
+
+    eventSource.addEventListener('log', (event) => {
+      retryCount = 0; // Reset retry count on successful message
+      const log = JSON.parse(event.data);
+      handleLog(log);
+    });
+
+    eventSource.addEventListener('error', () => {
+      eventSource.close();
+
+      if (retryCount < maxRetries) {
+        retryCount++;
+        console.log(`Reconnecting... (${retryCount}/${maxRetries})`);
+        setTimeout(connect, 2000 * retryCount); // Exponential backoff
+      } else {
+        console.error('Max retries reached');
+        showErrorMessage();
+      }
+    });
+
+    return eventSource;
+  };
+
+  return connect();
+};
+```
+
+## Production Considerations
+
+1. **Authentication**: Ensure proper auth tokens are sent with SSE requests
+2. **Error Handling**: Implement robust error handling and reconnection logic
+3. **Rate Limiting**: Be mindful of server resources and implement client-side throttling
+4. **Browser Compatibility**: SSE is supported in all modern browsers
+5. **Connection Limits**: Most browsers limit concurrent SSE connections per domain (typically 6)
+
+## Troubleshooting
+
+- **Connection closes immediately**: Check authentication token
+- **No logs received**: Verify task ID and user permissions
+- **Connection times out**: Check network stability and increase timeout parameter
+- **Server errors**: Check server logs for authentication or database issues