@codeguide/core 0.0.28 → 0.0.29

package/docs/README.md

@@ -0,0 +1,134 @@
+---
+layout: home
+
+hero:
+  name: "@codeguide/core"
+  text: "TypeScript SDK"
+  tagline: Complete TypeScript SDK for integrating CodeGuide functionality into your applications
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /codeguide-client
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/CodeGuide-dev/codeguide
+
+features:
+  - title: 🔑 Multiple Authentication Methods
+    details: Database API keys, legacy keys, and JWT tokens with automatic fallback
+  - title: 📝 Project Management
+    details: Create, update, and manage projects programmatically with full CRUD operations
+  - title: 🤖 Codespace Tasks
+    details: Create and manage AI-powered coding tasks with support for multiple execution modes
+  - title: 🎯 Model Management
+    details: Query and manage LLM models and providers for your codespace tasks
+  - title: 🔐 Security Keys
+    details: Securely manage provider API keys and GitHub tokens with encryption
+  - title: 🛡️ TypeScript Support
+    details: Full type safety and IntelliSense support for all API methods
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @codeguide/core
+```
+
+### Basic Usage
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+// Initialize the CodeGuide client
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_your_database_api_key', // Recommended
+})
+
+// Access services
+const projects = await codeguide.projects.getAllProjects()
+const tasks = await codeguide.codespace.getCodespaceTasksByProject({
+  project_id: 'your_project_id'
+})
+```
+
+## Documentation Structure
+
+### Core Components
+
+- **[CodeGuide Client](./codeguide-client.md)** - Main client class and initialization
+- **[Authentication](./authentication.md)** - Authentication methods and configuration
+
+### Services
+
+- **[Projects Service](./projects-service.md)** - Project management and repository connections
+- **[Codespace Service](./codespace-service.md)** - AI-powered coding tasks and workflows
+- **[Codespace Models](./codespace-models.md)** - LLM model providers and model management
+- **[Security Keys Service](./security-keys-service.md)** - Provider API keys and GitHub token management
+- **[Usage Service](./usage-service.md)** - Usage tracking and authorization
+
+## Features
+
+- 🔑 **Multiple Authentication Methods** - Database API keys, legacy keys, and JWT tokens
+- 📝 **Project Management** - Create, update, and manage projects programmatically
+- 🤖 **Codespace Tasks** - Create and manage AI-powered coding tasks
+- 🎯 **Model Management** - Query and manage LLM models and providers
+- 🔐 **Security Keys** - Securely manage provider API keys and GitHub tokens
+- 📊 **Usage Tracking** - Monitor API usage and credits
+- 🛡️ **TypeScript Support** - Full type safety and IntelliSense
+
+## Getting Started
+
+1. **Install the package**: `npm install @codeguide/core`
+2. **Get your API key**: Sign up at [codeguide.ai](https://codeguide.ai) to get your API key
+3. **Initialize the client**: See [CodeGuide Client](./codeguide-client.md) for setup instructions
+4. **Authenticate**: See [Authentication](./authentication.md) for authentication options
+5. **Start building**: Explore the service documentation to learn about available features
+
+## Common Use Cases
+
+### Creating a Project
+
+```typescript
+const project = await codeguide.projects.createProject({
+  title: 'My New Project',
+  description: 'Project description here'
+})
+```
+
+### Creating a Codespace Task
+
+```typescript
+const task = await codeguide.codespace.createCodespaceTaskV2({
+  project_id: project.id,
+  task_description: 'Implement user authentication',
+  execution_mode: 'implementation'
+})
+```
+
+### Managing Security Keys
+
+```typescript
+// Store a provider API key
+await codeguide.securityKeys.createProviderAPIKey({
+  provider_key: 'openai',
+  api_key: 'sk-your-openai-key'
+})
+
+// Store a GitHub token
+await codeguide.securityKeys.createGitHubToken({
+  github_token: 'ghp_your_github_token'
+})
+```
+
+## Support
+
+- **GitHub**: [CodeGuide Repository](https://github.com/CodeGuide-dev/codeguide)
+- **Issues**: [GitHub Issues](https://github.com/CodeGuide-dev/codeguide/issues)
+- **Documentation**: This documentation site
+
+## License
+
+MIT License - see the LICENSE file for details.

package/docs/README_SETUP.md

@@ -0,0 +1,46 @@
+# VitePress Setup Instructions
+
+## The Issue
+
+VitePress is an ESM-only package, but Node.js was trying to load it with CommonJS `require()`. This has been fixed by creating a separate `package.json` in the `docs/` directory with `"type": "module"`.
+
+## Setup Steps
+
+1. **Install dependencies in the docs directory**:
+   ```bash
+   cd packages/core
+   npm run docs:install
+   ```
+   
+   Or manually:
+   ```bash
+   cd packages/core/docs
+   npm install
+   ```
+
+2. **Start the development server**:
+   ```bash
+   cd packages/core
+   npm run docs:dev
+   ```
+
+3. **Open your browser**:
+   Navigate to http://localhost:5173
+
+## Available Commands
+
+From `packages/core/`:
+- `npm run docs:dev` - Start development server
+- `npm run docs:build` - Build for production
+- `npm run docs:preview` - Preview the built site
+- `npm run docs:install` - Install docs dependencies
+
+Or from `packages/core/docs/`:
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run preview` - Preview the built site
+
+## Why Separate package.json?
+
+The docs directory has its own `package.json` with `"type": "module"` to ensure VitePress (which is ESM-only) works correctly without affecting the main package's CommonJS setup.
+

package/docs/authentication.md

@@ -0,0 +1,351 @@
+# Authentication
+
+The CodeGuide client supports multiple authentication methods with automatic priority handling. This guide covers all available authentication options and how they work.
+
+## Overview
+
+The CodeGuide client automatically selects the best available authentication method based on priority:
+
+1. **Database API Key** (Highest Priority) - Recommended
+2. **Legacy API Key + User ID** (Medium Priority) - For backward compatibility
+3. **Clerk JWT Token** (Lowest Priority) - For Clerk-based applications
+
+## Authentication Methods
+
+### 1. Database API Key (Recommended)
+
+The recommended authentication method. Database API keys are prefixed with `sk_` and provide the most secure and flexible authentication.
+
+#### Configuration
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_your_database_api_key', // Must start with 'sk_'
+})
+```
+
+#### Features
+
+- Highest priority authentication method
+- No user ID required
+- Supports all API features
+- Can be scoped and managed through the API
+
+#### Getting Your Database API Key
+
+1. Sign up at [codeguide.ai](https://codeguide.ai)
+2. Navigate to API Keys section
+3. Create a new API key (format: `sk_...`)
+4. Copy and store securely
+
+### 2. Legacy API Key + User ID
+
+For backward compatibility with older integrations. Requires both an API key and user ID.
+
+#### Configuration
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  apiKey: 'your_legacy_api_key',
+  userId: 'your_user_id', // Required for legacy auth
+})
+```
+
+#### Features
+
+- Medium priority (used if database API key is not provided)
+- Requires both `apiKey` and `userId`
+- Backward compatible with older integrations
+
+### 3. Clerk JWT Token
+
+For applications using Clerk for authentication. Pass a valid Clerk JWT token.
+
+#### Configuration
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  jwtToken: 'your_clerk_jwt_token',
+})
+```
+
+#### Features
+
+- Lowest priority (used if no other auth method is available)
+- Requires valid Clerk JWT token
+- Useful for Clerk-based applications
+
+## Automatic Fallback
+
+The client automatically falls back through authentication methods based on priority:
+
+```typescript
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_key',     // Will try this first (Priority 1)
+  apiKey: 'legacy_key',         // Fallback if database key invalid (Priority 2)
+  userId: 'user_id',            // Required for legacy auth
+  jwtToken: 'jwt_token',        // Final fallback (Priority 3)
+})
+```
+
+**Priority Order:**
+1. Database API Key (`databaseApiKey` with `sk_` prefix)
+2. Legacy API Key + User ID (`apiKey` + `userId`)
+3. Clerk JWT Token (`jwtToken`)
+
+## Authentication Validation
+
+### Check Current Authentication Method
+
+```typescript
+const authMethod = codeguide.projects.getAuthenticationMethod()
+
+if (authMethod) {
+  console.log('Auth type:', authMethod.type)
+  console.log('Priority:', authMethod.priority)
+  console.log('Headers:', authMethod.headers)
+} else {
+  console.log('No authentication configured')
+}
+```
+
+### Validate Authentication Configuration
+
+```typescript
+const validation = codeguide.projects.validateAuthentication()
+
+if (validation.success) {
+  console.log('Authentication is valid')
+  console.log('Method:', validation.method?.type)
+} else {
+  console.error('Authentication error:', validation.error)
+}
+```
+
+## Error Handling
+
+### Authentication Errors
+
+All authentication errors are thrown with descriptive messages:
+
+```typescript
+try {
+  const projects = await codeguide.projects.getAllProjects()
+} catch (error) {
+  if (error.message.includes('401')) {
+    // Authentication failed
+    if (error.message.includes('Database API key')) {
+      console.error('Invalid database API key')
+    } else if (error.message.includes('Legacy API key')) {
+      console.error('Invalid legacy API key or user ID')
+    } else if (error.message.includes('Clerk JWT')) {
+      console.error('Invalid or expired JWT token')
+    }
+  }
+}
+```
+
+### Common Error Scenarios
+
+#### Invalid Database API Key
+
+```typescript
+// Error: Database API key authentication failed: Invalid, expired, or inactive API key
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_invalid_key',
+})
+```
+
+#### Missing User ID for Legacy Auth
+
+```typescript
+// Error: Legacy API key authentication requires both apiKey and userId
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  apiKey: 'legacy_key',
+  // userId is missing
+})
+```
+
+#### Invalid JWT Token
+
+```typescript
+// Error: Clerk JWT authentication failed: Invalid or expired token
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  jwtToken: 'expired_token',
+})
+```
+
+## Best Practices
+
+### 1. Use Environment Variables
+
+Store API keys securely in environment variables:
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+const codeguide = new CodeGuide({
+  baseUrl: process.env.CODEGUIDE_API_URL || 'https://api.codeguide.ai',
+  databaseApiKey: process.env.CODEGUIDE_API_KEY, // sk_...
+})
+```
+
+### 2. Prefer Database API Keys
+
+Use database API keys (`sk_...`) for new integrations:
+
+```typescript
+// ✅ Recommended
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_your_key',
+})
+
+// ❌ Avoid if possible
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  apiKey: 'legacy_key',
+  userId: 'user_id',
+})
+```
+
+### 3. Handle Authentication Errors Gracefully
+
+```typescript
+async function makeRequest() {
+  try {
+    return await codeguide.projects.getAllProjects()
+  } catch (error) {
+    if (error.message.includes('401')) {
+      // Retry with different auth method or show user-friendly error
+      throw new Error('Please check your API credentials')
+    }
+    throw error
+  }
+}
+```
+
+### 4. Validate Before Making Requests
+
+```typescript
+const validation = codeguide.projects.validateAuthentication()
+
+if (!validation.success) {
+  console.error('Authentication not configured:', validation.error)
+  return
+}
+
+// Proceed with API calls
+const projects = await codeguide.projects.getAllProjects()
+```
+
+### 5. Rotate Keys Regularly
+
+Regularly rotate your API keys for security:
+
+```typescript
+// Old key
+const oldCodeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_old_key',
+})
+
+// Create new key via API
+const newKey = await oldCodeguide.apiKeyEnhanced.createApiKey({
+  name: 'New Production Key',
+})
+
+// Update to new key
+const newCodeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: newKey.data.api_key,
+})
+```
+
+## Security Considerations
+
+### API Key Storage
+
+- **Never commit API keys to version control**
+- Use environment variables or secure key management services
+- Rotate keys regularly
+- Use different keys for different environments (dev, staging, production)
+
+### Key Scoping
+
+Database API keys can be scoped to specific permissions. Create keys with minimal required permissions:
+
+```typescript
+// Use scoped keys when possible
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: 'sk_readonly_key', // Scoped to read-only operations
+})
+```
+
+### Token Expiration
+
+- JWT tokens expire after a set period
+- Implement token refresh logic for Clerk-based applications
+- Handle token expiration errors gracefully
+
+## Examples
+
+### Basic Setup
+
+```typescript
+import { CodeGuide } from '@codeguide/core'
+
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: process.env.CODEGUIDE_API_KEY!,
+})
+```
+
+### With Fallback
+
+```typescript
+const codeguide = new CodeGuide({
+  baseUrl: 'https://api.codeguide.ai',
+  databaseApiKey: process.env.CODEGUIDE_API_KEY,
+  // Fallback to legacy auth if database key not available
+  apiKey: process.env.LEGACY_API_KEY,
+  userId: process.env.USER_ID,
+})
+```
+
+### Clerk Integration
+
+```typescript
+import { useAuth } from '@clerk/nextjs'
+
+function MyComponent() {
+  const { getToken } = useAuth()
+  
+  const codeguide = new CodeGuide({
+    baseUrl: 'https://api.codeguide.ai',
+    jwtToken: await getToken(),
+  })
+  
+  // Use codeguide...
+}
+```
+
+## Related Documentation
+
+- [CodeGuide Client](./codeguide-client.md) - Client initialization and configuration
+- [Security Keys Service](./security-keys-service.md) - Managing provider API keys
+