@codeguide/core 0.0.22 → 0.0.24

package/README.md

@@ -2,21 +2,39 @@
 
 The core package for CodeGuide with programmatic API access. This package provides TypeScript interfaces and services for integrating CodeGuide functionality into your applications.
 
+## Services Overview
+
+The `@codeguide/core` package provides a suite of services to interact with the CodeGuide API:
+
+- **[ApiKeyEnhancedService](#apikeyenhancedservice)**: Manages API keys with enhanced features.
+- **[ProjectService](#projectservice)**: Handles project creation, retrieval, and management.
+- **[TaskService](#taskservice)**: Organizes and tracks development tasks within projects.
+- **[CodespaceService](#codespaceservice)**: Manages AI-powered coding tasks, from generation to execution.
+- **[GenerationService](#generationservice)**: Provides AI-powered code and document generation.
+- **[RepositoryAnalysisService](#repositoryanalysisservice)**: Analyzes GitHub repositories for insights and documentation.
+- **[ExternalTokenService](#externaltokenservice)**: Securely stores and manages external API tokens (e.g., GitHub, GitLab).
+- **[SubscriptionService](#subscriptionservice)**: Manages user subscriptions and plans.
+- **[UsageService](#usageservice)**: Monitors API usage, credits, and service health.
+- **[CancellationFunnelService](#cancellationfunnelservice)**: Handles the subscription cancellation process.
+
 ## Features
 
-- 🔑 **API Key Management**: Full CRUD operations for API keys
-- 📝 **Project Management**: Create and manage projects programmatically
-- 🎯 **Task Management**: Organize and track development tasks
-- 📊 **Usage Analytics**: Monitor API usage and credits
-- 🔍 **Repository Analysis**: Analyze code repositories
-- 🎨 **Code Generation**: Generate code with AI assistance
-- 🔐 **Multiple Authentication**: Support for various auth methods
-- 🛡️ **TypeScript Support**: Full type safety and IntelliSense
+- 🔑 **API Key Management**: Full CRUD operations for API keys.
+- 📝 **Project Management**: Create and manage projects programmatically.
+- 🎯 **Task Management**: Organize and track development tasks.
+- 🤖 **Codespace Tasks**: Create and manage AI-powered coding tasks and workflows.
+- 🎨 **Code Generation**: Generate code, documentation, and more with AI assistance.
+- 🔍 **Repository Analysis**: Analyze code repositories for insights.
+- 🔐 **External Token Management**: Securely store and manage external tokens (e.g., GitHub, GitLab).
+- 💳 **Subscription Management**: Programmatically manage user subscriptions.
+- 📊 **Usage Analytics**: Monitor API usage and credits.
+- 🛡️ **TypeScript Support**: Full type safety and IntelliSense.
+- ⚙️ **Multiple Authentication Methods**: Flexible auth options including database API keys, legacy keys, and JWTs.
 
 ## Installation
 
 ```bash
-npm install @codeguide/core@0.0.11
+npm install @codeguide/core@0.0.23
 ```
 
 ## Quick Start
@@ -42,40 +60,30 @@ const newKey = await codeguide.apiKeyEnhanced.createApiKey({
 console.log(`Created key: ${newKey.data.api_key}`)
 ```
 
-### API Key Management
+### Codespace Task Management
 
 ```typescript
-import {
-  CodeGuide,
-  ApiKeyListResponse,
-  CreateApiKeyRequest
-} from '@codeguide/core'
+import { CodeGuide } from '@codeguide/core'
 
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
   databaseApiKey: 'sk_your_database_api_key'
 })
 
-// List all API keys
-const keysResponse: ApiKeyListResponse = await codeguide.apiKeyEnhanced.getAllApiKeys()
-
-// Check if you can create new keys
-const permission = await codeguide.apiKeyEnhanced.checkApiKeyPermission()
-if (permission.data.can_create) {
-  console.log('You can create new API keys')
-}
-
-// Create a new key
-const createRequest: CreateApiKeyRequest = {
-  name: 'Production Application'
-}
-const newKey = await codeguide.apiKeyEnhanced.createApiKey(createRequest)
+// Create a new codespace task for implementation
+const codespaceTask = await codeguide.codespace.createCodespaceTaskV2({
+  project_id: "your_project_id",
+  task_description: "Implement a new feature for real-time notifications",
+  execution_mode: "implementation"
+});
+console.log(`Created codespace task: ${codespaceTask.task_id}`);
 
-// Revoke a key
-await codeguide.apiKeyEnhanced.revokeApiKey('key-id-123')
+// Get task details
+const taskDetails = await codeguide.codespace.getCodespaceTask(codespaceTask.task_id);
+console.log(`Task status: ${taskDetails.data.status}`);
 ```
 
-### Project Management
+### Subscription Management
 
 ```typescript
 import { CodeGuide } from '@codeguide/core'
@@ -85,20 +93,16 @@ const codeguide = new CodeGuide({
   databaseApiKey: 'sk_your_database_api_key'
 })
 
-// Create a new project
-const project = await codeguide.projects.createProject({
-  title: 'My Web Application',
-  description: 'A modern web app built with React'
-})
-
-// Get project details
-const projectDetails = await codeguide.projects.getProject(project.id)
+// Get current subscription
+const subscription = await codeguide.subscription.getCurrentSubscription();
+console.log(`Current plan: ${subscription.data.product.name} (${subscription.data.subscription.status})`);
 
-// List all projects
-const projects = await codeguide.projects.getAllProjects()
+// Get all subscriptions (including historical)
+const allSubscriptions = await codeguide.subscription.getAllSubscriptions();
+console.log(`Found ${allSubscriptions.data.length} total subscriptions.`);
 ```
 
-### Task Management
+### External Token Management
 
 ```typescript
 import { CodeGuide } from '@codeguide/core'
@@ -108,20 +112,18 @@ const codeguide = new CodeGuide({
   databaseApiKey: 'sk_your_database_api_key'
 })
 
-// Generate tasks for a project
-const tasks = await codeguide.tasks.generateTasks({
-  project_id: 'project-id-123',
-  context: 'Building a React application with TypeScript'
-})
+// Store a GitHub token
+const storedToken = await codeguide.externalTokens.storeExternalToken({
+  platform: 'github',
+  token: 'ghp_your_github_token',
+  token_name: 'My Personal GitHub Token',
+  token_type: 'personal_access_token'
+});
+console.log(`Stored token with ID: ${storedToken.id}`);
 
-// Get all tasks for a project
-const projectTasks = await codeguide.tasks.getProjectTasks('project-id-123')
-
-// Update task status
-await codeguide.tasks.updateTask('task-id-123', {
-  status: 'in_progress',
-  notes: 'Started working on authentication module'
-})
+// List all stored GitHub tokens
+const githubTokens = await codeguide.externalTokens.listTokens({ platform: 'github' });
+console.log(`Found ${githubTokens.tokens.length} GitHub tokens.`);
 ```
 
 ## Authentication
@@ -130,6 +132,8 @@ The CodeGuide client supports multiple authentication methods with automatic pri
 
 ### 1. Database API Key (Highest Priority)
 
+Recommended method. The key must be prefixed with `sk_`.
+
 ```typescript
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
@@ -139,6 +143,8 @@ const codeguide = new CodeGuide({
 
 ### 2. Legacy API Key + User ID
 
+For backward compatibility.
+
 ```typescript
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
@@ -149,6 +155,8 @@ const codeguide = new CodeGuide({
 
 ### 3. Clerk JWT Token
 
+For applications using Clerk for authentication.
+
 ```typescript
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
@@ -158,13 +166,13 @@ const codeguide = new CodeGuide({
 
 ### Automatic Fallback
 
-The client automatically falls back through authentication methods:
+The client automatically falls back through authentication methods based on the priority order (1 > 2 > 3).
 
 ```typescript
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
   databaseApiKey: 'sk_key',        // Will try this first
-  apiKey: 'legacy_key',             // Fallback if database key fails
+  apiKey: 'legacy_key',             // Fallback if database key is invalid or missing
   userId: 'user_id',                // Required for legacy auth
   jwtToken: 'jwt_token'             // Final fallback
 })
@@ -174,161 +182,147 @@ const codeguide = new CodeGuide({
 
 ### ApiKeyEnhancedService
 
-#### getAllApiKeys()
-```typescript
-async getAllApiKeys(): Promise<ApiKeyListResponse>
-```
-Get all API keys for the authenticated user.
+- `getAllApiKeys(): Promise<ApiKeyListResponse>`
+- `createApiKey(request: CreateApiKeyRequest): Promise<CreateApiKeyResponse>`
+- `revokeApiKey(apiKeyId: string): Promise<RevokeApiKeyResponse>`
+- `checkApiKeyPermission(): Promise<ApiKeyPermissionResponse>`
+- `getApiKeyById(apiKeyId: string): Promise<ApiKeyResponse>`
 
-**Returns:** `Promise<ApiKeyListResponse>`
+### ProjectService
 
-**Example:**
-```typescript
-const response = await codeguide.apiKeyEnhanced.getAllApiKeys()
-console.log(response.data) // Array of ApiKey objects
-```
+- `getAllProjects(params?: GetProjectsRequest): Promise<Project[]>`
+- `getPaginatedProjects(params: PaginatedProjectsRequest): Promise<PaginatedProjectsResponse>`
+- `getProjectById(projectId: string): Promise<Project>`
+- `createProject(request: CreateProjectRequest): Promise<Project>`
+- `updateProject(projectId: string, request: UpdateProjectRequest): Promise<Project>`
+- `deleteProject(projectId: string): Promise<{ status: string; message: string }>`
+- `connectRepository(projectId: string, request: ConnectRepositoryRequest): Promise<ConnectRepositoryResponse>`
 
-#### createApiKey(request)
-```typescript
-async createApiKey(request: CreateApiKeyRequest): Promise<CreateApiKeyResponse>
-```
-Create a new API key.
+### TaskService
 
-**Parameters:**
-- `request.name` (string): Name for the new API key
+- `getAllTaskGroups(): Promise<TaskGroup[]>`
+- `getPaginatedTaskGroups(params: PaginatedTaskGroupsRequest): Promise<PaginatedTaskGroupsResponse>`
+- `createTaskGroup(request: CreateTaskGroupRequest): Promise<TaskGroup>`
+- `getProjectTaskById(taskId: string): Promise<ProjectTask>`
+- `createProjectTask(request: CreateProjectTaskRequest): Promise<ProjectTask>`
+- `updateProjectTask(taskId: string, request: UpdateProjectTaskRequest): Promise<ProjectTask>`
 
-**Returns:** `Promise<CreateApiKeyResponse>`
+### CodespaceService
 
-**Example:**
-```typescript
-const response = await codeguide.apiKeyEnhanced.createApiKey({
-  name: 'My Application'
-})
-console.log(response.data.api_key) // The new API key
-```
+- `createCodespaceTaskV2(request: CreateCodespaceTaskRequestV2): Promise<CreateCodespaceTaskResponseV2>`
+- `createBackgroundCodespaceTask(request: CreateBackgroundCodespaceTaskRequest): Promise<CreateBackgroundCodespaceTaskResponse>`
+- `getCodespaceTask(codespaceTaskId: string): Promise<GetCodespaceTaskResponse>`
+- `getCodespaceTasksByProject(params: GetCodespaceTasksByProjectRequest): Promise<GetCodespaceTasksByProjectResponse>`
+- `getCodespaceTaskDetailed(codespaceTaskId: string): Promise<CodespaceTaskDetailedResponse>`
 
-#### revokeApiKey(apiKeyId)
-```typescript
-async revokeApiKey(apiKeyId: string): Promise<RevokeApiKeyResponse>
-```
-Revoke an API key by ID.
+### GenerationService
 
-**Parameters:**
-- `apiKeyId` (string): ID of the API key to revoke
+- `refinePrompt(request: RefinePromptRequest): Promise<RefinePromptResponse>`
+- `generateTitle(request: GenerateTitleRequest): Promise<GenerateTitleResponse>`
+- `generatePRD(request: GeneratePRDRequest): Promise<GeneratePRDResponse>`
+- `generateDocument(request: GenerateDocumentRequest): Promise<GenerateDocumentResponse>`
+- `startBackgroundGeneration(request: BackgroundGenerationRequest): Promise<BackgroundGenerationResponse>`
+- `getBackgroundGenerationStatus(jobId: string): Promise<BackgroundGenerationStatusResponse>`
 
-**Returns:** `Promise<RevokeApiKeyResponse>`
+### RepositoryAnalysisService
 
-#### checkApiKeyPermission()
-```typescript
-async checkApiKeyPermission(): Promise<ApiKeyPermissionResponse>
-```
-Check if the user can create new API keys.
+- `analyzeRepository(request: AnalyzeRepositoryRequest): Promise<AnalyzeRepositoryResponse>`
+- `getAnalysisStatus(taskId: string): Promise<RepositoryAnalysisStatusResponse>`
+- `getAnalysisResult(taskId: string): Promise<RepositoryAnalysisResultResponse>`
+- `listRepositories(skip?: number, limit?: number): Promise<RepositoryListResponse>`
 
-**Returns:** `Promise<ApiKeyPermissionResponse>`
+### ExternalTokenService
 
-### ProjectService
+- `storeExternalToken(request: StoreExternalTokenRequest): Promise<StoreExternalTokenResponse>`
+- `listTokens(query?: ListTokensQuery): Promise<ListTokensResponse>`
+- `getToken(tokenId: string): Promise<GetTokenResponse>`
+- `validateToken(request: ValidateTokenRequest): Promise<ValidateTokenResponse>`
+- `findBestMatch(request: FindBestMatchRequest): Promise<FindBestMatchResponse>`
+- `revokeToken(tokenId: string): Promise<RevokeTokenResponse>`
 
-#### createProject(request)
-```typescript
-async createProject(request: CreateProjectRequest): Promise<ProjectResponse>
-```
-Create a new project.
-
-#### getProject(projectId)
-```typescript
-async getProject(projectId: string): Promise<ProjectResponse>
-```
-Get project details by ID.
-
-#### getAllProjects()
-```typescript
-async getAllProjects(): Promise<ProjectsListResponse>
-```
-Get all projects for the authenticated user.
+### SubscriptionService
 
-### TaskService
+- `getCurrentSubscription(): Promise<CurrentSubscriptionResponse>`
+- `getAllSubscriptions(): Promise<UserSubscriptionsResponse>`
+- `cancelSubscription(subscriptionId: string, request: CancelSubscriptionRequest): Promise<CancelSubscriptionResponse>`
+- `getSubscriptionById(subscriptionId: string): Promise<any>`
 
-#### generateTasks(request)
-```typescript
-async generateTasks(request: GenerateTasksRequest): Promise<TasksResponse>
-```
-Generate tasks for a project.
+### UsageService
 
-#### getProjectTasks(projectId)
-```typescript
-async getProjectTasks(projectId: string): Promise<TasksResponse>
-```
-Get all tasks for a project.
+- `getCreditBalance(): Promise<CreditBalanceResponse>`
+- `getUsageSummary(params?: UsageSummaryRequest): Promise<UsageSummaryResponse>`
+- `checkCredits(params: CreditCheckRequest): Promise<CreditCheckResponse>`
+- `healthCheck(): Promise<boolean>`
 
-#### updateTask(taskId, update)
-```typescript
-async updateTask(taskId: string, update: UpdateTaskRequest): Promise<TaskResponse>
-```
-Update task status and notes.
+### CancellationFunnelService
+- `initiateCancellation(request: CancellationFunnelInitiateRequest): Promise<CancellationFunnelInitiateResponse>`
+- `logSurveyResponse(request: CancellationFunnelSurveyRequest): Promise<CancellationFunnelSurveyResponse>`
+- `getCancellationFunnelStatus(subscriptionId: string): Promise<any>`
 
 ## Types
 
-### ApiKey
+The package exports all necessary types for requests and responses.
+
+### Core Types
 ```typescript
-interface ApiKey {
-  id: string
-  key: string           // Full API key string
-  user_id: string
-  name: string
-  created_at: string
-  expires_at?: string
-  is_active: boolean
-  metadata?: Record<string, any>
+interface APIServiceConfig {
+  baseUrl: string
+  databaseApiKey?: string    // Highest priority (sk_...)
+  apiKey?: string           // Legacy API key
+  userId?: string           // Required for legacy auth
+  jwtToken?: string         // Clerk JWT token
+  timeout?: number          // Default: 3600000 (1 hour)
 }
-```
 
-### ApiKeyListResponse
-```typescript
-interface ApiKeyListResponse {
-  status: string
-  data: ApiKey[]
+interface CodeGuideOptions {
+  language?: string
+  context?: string
+  verbose?: boolean
 }
 ```
 
-### CreateApiKeyRequest
+### Key Service Types
 ```typescript
-interface CreateApiKeyRequest {
-  name: string
+// projects/project-types.ts
+interface Project {
+  id: string
+  title: string
+  description: string
+  project_repositories: ProjectRepository[]
+  // ... and more
 }
-```
 
-### CreateApiKeyResponse
-```typescript
-interface CreateApiKeyResponse {
-  status: string
-  data: {
-    api_key: string
-    id: string
-    name: string
-    created_at: string
-    expires_at?: string
-    is_active: boolean
-    metadata?: Record<string, any>
-  }
-  message?: string
+// codespace/codespace-types.ts
+interface CreateCodespaceTaskRequestV2 {
+  project_id: string
+  task_description: string
+  execution_mode?: 'implementation' | 'docs-only'
+  // ... and more
 }
-```
 
-### APIServiceConfig
-```typescript
-interface APIServiceConfig {
-  baseUrl: string
-  databaseApiKey?: string    // Highest priority
-  apiKey?: string           // Legacy API key
-  userId?: string           // Required for legacy auth
-  jwtToken?: string         // Clerk JWT token
-  timeout?: number          // Default: 3600000 (1 hour)
+// external-tokens/external-tokens-types.ts
+type Platform = 'github' | 'gitlab' | 'bitbucket'
+interface StoreExternalTokenRequest {
+  platform: Platform
+  token: string
+  token_name: string
+  token_type: TokenType
+  // ... and more
+}
+
+// types.ts
+interface Subscription {
+  id: string
+  status: 'active' | 'canceled' | 'trialing' | ...
+  // ... and more
 }
 ```
 
+For a full list of types, please refer to the source files in `services/**/**-types.ts` and `types.ts`.
+
 ## Error Handling
 
-The client provides detailed error information:
+The client provides detailed error information for failed API calls. It is recommended to wrap API calls in a `try...catch` block.
 
 ```typescript
 try {
@@ -350,6 +344,8 @@ try {
 
 ### Timeout Configuration
 
+You can configure the request timeout (in milliseconds). The default is 1 hour.
+
 ```typescript
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
@@ -360,6 +356,8 @@ const codeguide = new CodeGuide({
 
 ### Verbose Logging
 
+Enable verbose logging to see detailed request and response information in the console.
+
 ```typescript
 const codeguide = new CodeGuide({
   baseUrl: 'https://api.codeguide.ai',
@@ -369,120 +367,6 @@ const codeguide = new CodeGuide({
 })
 ```
 
-## Advanced Usage
-
-### Custom Headers
-
-The BaseService allows you to intercept and modify requests:
-
-```typescript
-// Access the underlying axios instance
-const client = codeguide.apiKeyEnhanced.client
-
-// Add custom headers
-client.interceptors.request.use(config => {
-  config.headers['X-Custom-Header'] = 'value'
-  return config
-})
-```
-
-### Response Interceptors
-
-```typescript
-// Add custom response handling
-client.interceptors.response.use(
-  response => response,
-  error => {
-    // Custom error handling
-    console.error('API Error:', error.response?.data)
-    return Promise.reject(error)
-  }
-)
-```
-
-## Examples
-
-### Complete API Key Management Flow
-
-```typescript
-import { CodeGuide } from '@codeguide/core'
-
-async function manageApiKeys() {
-  const codeguide = new CodeGuide({
-    baseUrl: 'https://api.codeguide.ai',
-    databaseApiKey: 'sk_your_key'
-  })
-
-  try {
-    // Check permissions
-    const permission = await codeguide.apiKeyEnhanced.checkApiKeyPermission()
-    if (!permission.data.can_create) {
-      console.log('Cannot create new keys:', permission.data.reason)
-      return
-    }
-
-    // List current keys
-    const currentKeys = await codeguide.apiKeyEnhanced.getAllApiKeys()
-    console.log(`Current keys: ${currentKeys.data.length}`)
-
-    // Create new key
-    const newKey = await codeguide.apiKeyEnhanced.createApiKey({
-      name: 'Production Application'
-    })
-    console.log('Created key:', newKey.data.api_key)
-
-    // Revoke old key if needed
-    if (currentKeys.data.length > 5) {
-      await codeguide.apiKeyEnhanced.revokeApiKey(currentKeys.data[0].id)
-      console.log('Revoked oldest key')
-    }
-
-  } catch (error) {
-    console.error('API key management failed:', error.message)
-  }
-}
-```
-
-### Project Setup with Tasks
-
-```typescript
-import { CodeGuide } from '@codeguide/core'
-
-async function setupProject() {
-  const codeguide = new CodeGuide({
-    baseUrl: 'https://api.codeguide.ai',
-    databaseApiKey: 'sk_your_key'
-  })
-
-  try {
-    // Create project
-    const project = await codeguide.projects.createProject({
-      title: 'E-commerce Platform',
-      description: 'Modern e-commerce solution with React and Node.js'
-    })
-
-    // Generate tasks
-    const tasks = await codeguide.tasks.generateTasks({
-      project_id: project.id,
-      context: 'Building a full-stack e-commerce platform'
-    })
-
-    console.log(`Created project with ${tasks.data.length} tasks`)
-
-    // Start first task
-    if (tasks.data.length > 0) {
-      await codeguide.tasks.updateTask(tasks.data[0].id, {
-        status: 'in_progress',
-        notes: 'Starting project setup'
-      })
-    }
-
-  } catch (error) {
-    console.error('Project setup failed:', error.message)
-  }
-}
-```
-
 ## Contributing
 
 1. Fork the repository
@@ -500,4 +384,4 @@ async function setupProject() {
 
 ## License
 
-MIT License - see [LICENSE](../../LICENSE) file for details.
+MIT License - see the LICENSE file for details.

package/dist/examples/project-filtering-example.d.ts

@@ -0,0 +1,2 @@
+declare function demonstrateProjectFiltering(): Promise<void>;
+export { demonstrateProjectFiltering };