@codeguide/core

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: Manages API keys with enhanced features.
- ProjectService: Handles project creation, retrieval, and management.
- TaskService: Organizes and tracks development tasks within projects.
- CodespaceService: Manages AI-powered coding tasks, from generation to execution.
- GenerationService: Provides AI-powered code and document generation.
- RepositoryAnalysisService: Analyzes GitHub repositories for insights and documentation.
- ExternalTokenService: Securely stores and manages external API tokens (e.g., GitHub, GitLab).
- SubscriptionService: Manages user subscriptions and plans.
- UsageService: Monitors API usage, credits, and service health.
- 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.
- 🤖 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.23
`

Quick Start

$3

`typescript
import { CodeGuide } from '@codeguide/core'

const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_database_api_key',
})

// Get all API keys
const keysResponse = await codeguide.apiKeyEnhanced.getAllApiKeys()
console.log(Found ${keysResponse.data.length} API keys)

// Create a new API key
const newKey = await codeguide.apiKeyEnhanced.createApiKey({
name: 'My Application',
})
console.log(Created key: ${newKey.data.api_key})
`

$3

`typescript
import { CodeGuide } from '@codeguide/core'

const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_database_api_key',
})

// 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})

// Get task details
const taskDetails = await codeguide.codespace.getCodespaceTask(codespaceTask.task_id)
console.log(Task status: ${taskDetails.data.status})
`

$3

`typescript
import { CodeGuide } from '@codeguide/core'

const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_database_api_key',
})

// Get current subscription
const subscription = await codeguide.subscription.getCurrentSubscription()
console.log(
Current plan: ${subscription.data.product.name} (${subscription.data.subscription.status})
)

// Get all subscriptions (including historical)
const allSubscriptions = await codeguide.subscription.getAllSubscriptions()
console.log(Found ${allSubscriptions.data.length} total subscriptions.)
`

$3

`typescript
import { CodeGuide } from '@codeguide/core'

const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_database_api_key',
})

// 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})

// List all stored GitHub tokens
const githubTokens = await codeguide.externalTokens.listTokens({ platform: 'github' })
console.log(Found ${githubTokens.tokens.length} GitHub tokens.)
`

Authentication

The CodeGuide client supports multiple authentication methods with automatic priority handling:

$3

Recommended method. The key must be prefixed with sk_.

`typescript
const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_database_api_key',
})
`

$3

For backward compatibility.

`typescript
const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
apiKey: 'your_api_key',
userId: 'your_user_id',
})
`

$3

For applications using Clerk for authentication.

`typescript
const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
jwtToken: 'your_jwt_token',
})
`

$3

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 is invalid or missing
userId: 'user_id', // Required for legacy auth
jwtToken: 'jwt_token', // Final fallback
})
`

API Reference

$3

- getAllApiKeys(): Promise
- createApiKey(request: CreateApiKeyRequest): Promise
- revokeApiKey(apiKeyId: string): Promise
- checkApiKeyPermission(): Promise
- getApiKeyById(apiKeyId: string): Promise

$3

- getAllProjects(params?: GetProjectsRequest): Promise
- getPaginatedProjects(params: PaginatedProjectsRequest): Promise
- getProjectById(projectId: string): Promise
- createProject(request: CreateProjectRequest): Promise
- updateProject(projectId: string, request: UpdateProjectRequest): Promise
- deleteProject(projectId: string): Promise<{ status: string; message: string }>
- connectRepository(projectId: string, request: ConnectRepositoryRequest): Promise

$3

- getAllTaskGroups(): Promise
- getPaginatedTaskGroups(params: PaginatedTaskGroupsRequest): Promise
- createTaskGroup(request: CreateTaskGroupRequest): Promise
- getProjectTaskById(taskId: string): Promise
- createProjectTask(request: CreateProjectTaskRequest): Promise
- updateProjectTask(taskId: string, request: UpdateProjectTaskRequest): Promise

$3

- createCodespaceTaskV2(request: CreateCodespaceTaskRequestV2): Promise
- createBackgroundCodespaceTask(request: CreateBackgroundCodespaceTaskRequest): Promise
- getCodespaceTask(codespaceTaskId: string): Promise
- getCodespaceTasksByProject(params: GetCodespaceTasksByProjectRequest): Promise
- getCodespaceTaskDetailed(codespaceTaskId: string): Promise

$3

- refinePrompt(request: RefinePromptRequest): Promise
- generateTitle(request: GenerateTitleRequest): Promise
- generatePRD(request: GeneratePRDRequest): Promise
- generateDocument(request: GenerateDocumentRequest): Promise
- startBackgroundGeneration(request: BackgroundGenerationRequest): Promise
- getBackgroundGenerationStatus(jobId: string): Promise

$3

- analyzeRepository(request: AnalyzeRepositoryRequest): Promise
- getAnalysisStatus(taskId: string): Promise
- getAnalysisResult(taskId: string): Promise
- listRepositories(skip?: number, limit?: number): Promise

$3

- storeExternalToken(request: StoreExternalTokenRequest): Promise
- listTokens(query?: ListTokensQuery): Promise
- getToken(tokenId: string): Promise
- validateToken(request: ValidateTokenRequest): Promise
- findBestMatch(request: FindBestMatchRequest): Promise
- revokeToken(tokenId: string): Promise

$3

- getCurrentSubscription(): Promise
- getAllSubscriptions(): Promise
- cancelSubscription(subscriptionId: string, request: CancelSubscriptionRequest): Promise
- getSubscriptionById(subscriptionId: string): Promise

$3

- getCreditBalance(): Promise
- getUsageSummary(params?: UsageSummaryRequest): Promise
- checkCredits(params: CreditCheckRequest): Promise
- getAuthorization(): Promise
- healthCheck(): Promise

$3

- initiateCancellation(request: CancellationFunnelInitiateRequest): Promise
- logSurveyResponse(request: CancellationFunnelSurveyRequest): Promise
- getCancellationFunnelStatus(subscriptionId: string): Promise

Types

The package exports all necessary types for requests and responses.

$3

`typescript
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)
}

interface CodeGuideOptions {
language?: string
context?: string
verbose?: boolean
}
`

$3

`typescript
// projects/project-types.ts
interface Project {
id: string
title: string
description: string
project_repositories: ProjectRepository[]
// ... and more
}

// codespace/codespace-types.ts
interface CreateCodespaceTaskRequestV2 {
project_id: string
task_description: string
execution_mode?: 'implementation' | 'docs-only' | 'direct'
// ... and more
}

// 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 for failed API calls. It is recommended to wrap API calls in a try...catch block.

`typescript
try {
const keys = await codeguide.apiKeyEnhanced.getAllApiKeys()
} catch (error) {
if (error.message.includes('401')) {
console.error('Authentication failed:', error.message)
} else if (error.message.includes('403')) {
console.error('Permission denied:', error.message)
} else if (error.message.includes('429')) {
console.error('Rate limited:', error.message)
} else {
console.error('API error:', error.message)
}
}
`

Configuration

$3

You can configure the request timeout (in milliseconds). The default is 1 hour.

`typescript
const codeguide = new CodeGuide({
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_key',
timeout: 1800000, // 30 minutes
})
`

$3

Enable verbose logging to see detailed request and response information in the console.

`typescript
const codeguide = new CodeGuide(
{
baseUrl: 'https://api.codeguide.ai',
databaseApiKey: 'sk_your_key',
},
{
verbose: true, // Enable detailed logging
}
)
``

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

- Documentation: Main README
- CLI Package: @codeguide/cli
- Issues: GitHub Issues
- Discussions: GitHub Discussions

License

MIT License - see the LICENSE file for details.