@codeguide/core 0.0.1

package/dist/services/usage/usage-service.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageService = void 0;
+const base_service_1 = require("../base/base-service");
+class UsageService extends base_service_1.BaseService {
+    async trackUsage(request) {
+        return this.post('/usage/track', request);
+    }
+    async getCreditBalance() {
+        return this.get('/usage/credit-balance');
+    }
+    async checkCredits(params) {
+        const queryParams = new URLSearchParams();
+        if (params.input_tokens !== undefined)
+            queryParams.append('input_tokens', params.input_tokens.toString());
+        if (params.output_tokens !== undefined)
+            queryParams.append('output_tokens', params.output_tokens.toString());
+        if (params.call_seconds !== undefined)
+            queryParams.append('call_seconds', params.call_seconds.toString());
+        const url = `/usage/credit-check?${queryParams.toString()}`;
+        return this.get(url);
+    }
+    async getUsageSummary(params) {
+        const queryParams = new URLSearchParams();
+        if (params?.start_date)
+            queryParams.append('start_date', params.start_date);
+        if (params?.end_date)
+            queryParams.append('end_date', params.end_date);
+        const url = `/usage/summary${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+        return this.get(url);
+    }
+    async getAuthorization() {
+        return this.get('/usage/authorization');
+    }
+    async getFreeUserStatus() {
+        return this.get('/usage/free-user-status');
+    }
+    async calculateUsageCost(params) {
+        const queryParams = new URLSearchParams();
+        queryParams.append('model_key', params.model_key);
+        if (params.input_tokens !== undefined)
+            queryParams.append('input_tokens', params.input_tokens.toString());
+        if (params.output_tokens !== undefined)
+            queryParams.append('output_tokens', params.output_tokens.toString());
+        if (params.call_seconds !== undefined)
+            queryParams.append('call_seconds', params.call_seconds.toString());
+        if (params.cost_amount !== undefined)
+            queryParams.append('cost_amount', params.cost_amount.toString());
+        const url = `/usage/calculate?${queryParams.toString()}`;
+        return this.get(url);
+    }
+    async trackCodespaceUsage(request) {
+        return this.post('/usage/codespace/track', request);
+    }
+    async getCodespaceTaskUsage(codespaceTaskId) {
+        return this.get(`/usage/codespace/task/${codespaceTaskId}`);
+    }
+    async healthCheck() {
+        try {
+            const response = await this.get('/usage/health');
+            return response.status === 'healthy';
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.UsageService = UsageService;

package/dist/services/usage/usage-types.d.ts

@@ -0,0 +1,133 @@
+export interface TrackUsageRequest {
+    model_key: string;
+    input_tokens: number;
+    output_tokens: number;
+    call_seconds?: number;
+    cost_amount?: number;
+}
+export interface TrackUsageResponse {
+    success: boolean;
+    credits_used: number;
+    remaining_credits: number;
+    message: string;
+}
+export interface CreditBalanceResponse {
+    user_id: string;
+    total_consumed: number;
+    total_allotted: number;
+    remaining_credits: number;
+    utilization_percentage: number;
+    billing_cycle_start: string;
+    billing_cycle_end: string;
+    subscription: {
+        plan: string;
+        status: string;
+    };
+}
+export interface CreditCheckRequest {
+    model_key: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    call_seconds?: number;
+}
+export interface CreditCheckResponse {
+    has_sufficient_credits: boolean;
+    estimated_cost: number;
+    remaining_credits: number;
+    model_key: string;
+}
+export interface UsageSummaryRequest {
+    start_date?: string;
+    end_date?: string;
+}
+export interface UsageSummaryResponse {
+    user_id: string;
+    period: {
+        start_date: string;
+        end_date: string;
+    };
+    usage_summary: {
+        total_credits_used: number;
+        total_calls: number;
+        model_breakdown: Record<string, any>;
+        daily_usage: Array<{
+            date: string;
+            credits_used: number;
+            calls: number;
+        }>;
+    };
+    subscription: {
+        plan: string;
+        status: string;
+    };
+}
+export interface AuthorizationResponse {
+    user_id: string;
+    subscription: {
+        plan: string;
+        status: string;
+        features: string[];
+    };
+    usage_limits: {
+        monthly_credits: number;
+        max_calls_per_day: number;
+    };
+    permissions: string[];
+}
+export interface FreeUserStatusResponse {
+    is_free_user: boolean;
+    has_available_credits: boolean;
+    credits_remaining: number;
+    credits_expire_at?: string;
+}
+export interface CalculateUsageRequest {
+    model_key: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    call_seconds?: number;
+    cost_amount?: number;
+}
+export interface CalculateUsageResponse {
+    model_key: string;
+    estimated_cost: number;
+    calculation_breakdown: {
+        input_cost: number;
+        output_cost: number;
+        time_cost: number;
+        total_cost: number;
+    };
+}
+export interface TrackCodespaceUsageRequest {
+    codespace_task_id: string;
+    model_key: string;
+    input_tokens: number;
+    output_tokens: number;
+    call_seconds?: number;
+    cost_amount?: number;
+}
+export interface TrackCodespaceUsageResponse {
+    id: string;
+    codespace_task_id: string;
+    user_id: string;
+    model_key: string;
+    input_tokens: number;
+    output_tokens: number;
+    call_seconds: number;
+    cost_amount: number;
+    created_at: string;
+}
+export interface CodespaceTaskUsageResponse {
+    codespace_task_id: string;
+    total_usage: {
+        total_input_tokens: number;
+        total_output_tokens: number;
+        total_call_seconds: number;
+        total_cost: number;
+    };
+    usage_records: TrackCodespaceUsageResponse[];
+}
+export interface HealthResponse {
+    status: string;
+    timestamp: string;
+    version: string;
+}

package/dist/services/usage/usage-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+export interface CodeGuideRequest {
+    prompt: string;
+    language?: string;
+    context?: string;
+}
+export interface CodeGuideResponse {
+    id?: string;
+    response?: string;
+    refined_prompt?: string;
+    content?: string;
+    timestamp: string;
+    language?: string;
+}
+export interface APIServiceConfig {
+    baseUrl: string;
+    databaseApiKey?: string;
+    apiKey?: string;
+    userId?: string;
+    jwtToken?: string;
+    timeout?: number;
+}
+export interface AuthenticationMethod {
+    type: 'database-api-key' | 'legacy-api-key' | 'clerk-jwt';
+    priority: number;
+    headers: Record<string, string>;
+}
+export interface AuthenticationResult {
+    success: boolean;
+    method?: AuthenticationMethod;
+    user?: {
+        id: string;
+        email?: string;
+        subscriptionStatus?: string;
+        creditsRemaining?: number;
+    };
+    error?: string;
+}
+export interface CodeGuideOptions {
+    language?: string;
+    context?: string;
+    verbose?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/index.ts

@@ -0,0 +1,12 @@
+import dotenv from 'dotenv'
+import path from 'path'
+
+// Load environment variables from project root
+dotenv.config({
+  path: path.resolve(__dirname, '../../../.env'),
+  quiet: true,
+})
+
+export { CodeGuide } from './codeguide'
+export * from './services'
+export * from './types'

package/jest.config.json

@@ -0,0 +1,19 @@
+{
+  "preset": "ts-jest",
+  "testEnvironment": "node",
+  "roots": ["<rootDir>"],
+  "testMatch": ["**/__tests__/**/*.test.ts"],
+  "transform": {
+    "^.+\\.ts$": "ts-jest"
+  },
+  "collectCoverageFrom": [
+    "**/*.ts",
+    "!**/*.d.ts",
+    "!**/index.ts",
+    "!**/node_modules/**",
+    "!**/__tests__/**"
+  ],
+  "coverageDirectory": "coverage",
+  "coverageReporters": ["text", "lcov"],
+  "setupFilesAfterEnv": ["<rootDir>/../../jest.setup.js"]
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@codeguide/core",
+  "version": "0.0.1",
+  "description": "Core package for code guidance with programmatic API",
+  "main": "dist/index.js",
+  "types": "dist/index.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"
+  },
+  "keywords": [
+    "api",
+    "typescript",
+    "code",
+    "development",
+    "productivity",
+    "ai",
+    "sdk"
+  ],
+  "author": "CodeGuide Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CodeGuide-dev/codeguide.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CodeGuide-dev/codeguide/issues"
+  },
+  "homepage": "https://github.com/CodeGuide-dev/codeguide#readme",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "dotenv": "^17.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "axios-mock-adapter": "^1.22.0",
+    "@types/dotenv": "^6.1.1"
+  }
+}

package/services/README.md

@@ -0,0 +1,113 @@
+# CodeGuide API Services
+
+This directory contains modular services for interacting with different CodeGuide API endpoints.
+
+## Available Services
+
+### 1. GenerationService (`/generate`)
+
+Handles AI-powered content generation:
+
+- `refinePrompt()` - Refine user prompts
+- `generateTitle()` - Generate project titles
+- `generateQuestionnaire()` - Generate questionnaires
+- `generatePRD()` - Generate Project Requirements Documents
+- `generateCategory()` - Suggest project categories
+- `generateOutline()` - Generate document outlines
+- `generateDocument()` - Generate custom documents
+- `generateMultipleDocuments()` - Generate multiple documents in parallel
+- `startBackgroundGeneration()` - Start background generation jobs
+- `getBackgroundGenerationStatus()` - Check background job status
+
+### 2. ProjectService (`/projects`)
+
+Manages projects:
+
+- `getAllProjects()` - Get all user projects
+- `getPaginatedProjects()` - Get paginated projects with filtering
+- `getProjectById()` - Get specific project
+- `createProject()` - Create new project
+- `updateProject()` - Update existing project
+- `deleteProject()` - Delete project
+
+### 3. UsageService (`/usage`)
+
+Handles usage tracking and credits:
+
+- `trackUsage()` - Track API usage
+- `getCreditBalance()` - Get current credit balance
+- `checkCredits()` - Check if sufficient credits available
+- `getUsageSummary()` - Get detailed usage summary
+- `getAuthorization()` - Get user authorization status
+- `getFreeUserStatus()` - Check free user status
+- `calculateUsageCost()` - Calculate usage costs
+- `trackCodespaceUsage()` - Track codespace usage
+- `getCodespaceTaskUsage()` - Get codespace usage details
+- `healthCheck()` - Check API health
+
+### 4. RepositoryAnalysisService (`/repository-analysis`)
+
+Analyzes GitHub repositories:
+
+- `analyzeRepository()` - Start repository analysis
+- `getAnalysisStatus()` - Check analysis status
+- `getAnalysisResult()` - Get analysis results
+- `listRepositories()` - List analyzed repositories
+- `getRepositoryDetails()` - Get repository details
+- `deleteRepository()` - Delete repository analysis
+
+### 5. TaskService (`/task-groups`, `/project-tasks`)
+
+Manages task groups and project tasks:
+
+- **Task Groups**: CRUD operations for task groups
+- **Project Tasks**: CRUD operations for project tasks
+- **Pagination**: Support for paginated results
+- **Filtering**: Filter by status, project, parent task, etc.
+
+### 6. BaseService
+
+Base class providing common functionality:
+
+- HTTP client setup with proper headers
+- Error handling with standardized responses
+- Authentication handling (API Key + User ID)
+- Request/response interceptors
+- Common HTTP methods (GET, POST, PUT, DELETE)
+
+## Usage Example
+
+```typescript
+import { CodeGuide, APIServiceConfig } from '@codeguide/core'
+
+const config: APIServiceConfig = {
+  baseUrl: 'https://api.codeguide.app',
+  apiKey: 'your-api-key',
+  userId: 'your-user-id',
+}
+
+const codeguide = new CodeGuide(config)
+
+// Use different services
+const projects = await codeguide.projects.getAllProjects()
+const creditBalance = await codeguide.usage.getCreditBalance()
+const refinedPrompt = await codeguide.generation.refinePrompt({
+  user_prompt: 'How do I create a React component?',
+})
+```
+
+## Configuration
+
+All services accept the same configuration:
+
+- `baseUrl`: API base URL (defaults to https://api.codeguide.app)
+- `apiKey`: API key for authentication
+- `userId`: User ID for authentication
+- `timeout`: Request timeout (default: 3600000ms / 1 hour)
+
+## Authentication
+
+Services use the CodeGuide API authentication scheme:
+
+- Primary: `X-API-Key` + `X-User-ID` headers
+- Fallback: `Authorization: Bearer <token>`

package/services/base/base-service.ts

@@ -0,0 +1,230 @@
+import axios, { AxiosInstance, AxiosResponse } from 'axios'
+import { APIServiceConfig, AuthenticationMethod, AuthenticationResult } from '../../types'
+
+export abstract class BaseService {
+  protected client: AxiosInstance
+  protected config: APIServiceConfig
+
+  constructor(config: APIServiceConfig) {
+    this.config = config
+
+    // Ensure baseUrl includes the API version
+    const baseUrl = config.baseUrl
+
+    this.client = axios.create({
+      baseURL: baseUrl,
+      timeout: config.timeout || 3600000, // 1 hour timeout for document generation
+      headers: this.getAuthenticationHeaders(),
+    })
+
+    this.setupInterceptors()
+  }
+
+  /**
+   * Determine and return authentication headers based on priority
+   * Priority: 1. Database API Key, 2. Legacy API Key, 3. Clerk JWT
+   */
+  private getAuthenticationHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    // Priority 1: Database API Key (format: sk_...)
+    if (this.config.databaseApiKey && this.config.databaseApiKey.startsWith('sk_')) {
+      headers['Authorization'] = `Bearer ${this.config.databaseApiKey}`
+      return headers
+    }
+
+    return headers
+  }
+
+  /**
+   * Get the current authentication method being used
+   */
+  public getAuthenticationMethod(): AuthenticationMethod | null {
+    // Priority 1: Database API Key
+    if (this.config.databaseApiKey && this.config.databaseApiKey.startsWith('sk_')) {
+      return {
+        type: 'database-api-key',
+        priority: 1,
+        headers: {
+          Authorization: `Bearer ${this.config.databaseApiKey}`,
+          'Content-Type': 'application/json',
+        },
+      }
+    }
+
+    // Priority 2: Legacy API Key + User ID
+    if (this.config.apiKey && this.config.userId) {
+      return {
+        type: 'legacy-api-key',
+        priority: 2,
+        headers: {
+          'X-API-Key': this.config.apiKey,
+          'X-User-ID': this.config.userId,
+          'Content-Type': 'application/json',
+        },
+      }
+    }
+
+    // Priority 3: Clerk JWT Token
+    if (this.config.jwtToken) {
+      return {
+        type: 'clerk-jwt',
+        priority: 3,
+        headers: {
+          Authorization: `Bearer ${this.config.jwtToken}`,
+          'Content-Type': 'application/json',
+        },
+      }
+    }
+
+    // Fallback: Legacy API key without user ID
+    if (this.config.apiKey) {
+      return {
+        type: 'legacy-api-key',
+        priority: 2,
+        headers: {
+          'X-API-Key': this.config.apiKey,
+          'Content-Type': 'application/json',
+        },
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Validate the current authentication configuration
+   */
+  public validateAuthentication(): AuthenticationResult {
+    const method = this.getAuthenticationMethod()
+
+    if (!method) {
+      return {
+        success: false,
+        error:
+          'No authentication method configured. Please provide either databaseApiKey, apiKey + userId, or jwtToken.',
+      }
+    }
+
+    // Validate database API key format
+    if (method.type === 'database-api-key') {
+      if (!this.config.databaseApiKey?.startsWith('sk_')) {
+        return {
+          success: false,
+          error: 'Database API key must start with "sk_"',
+        }
+      }
+    }
+
+    // Validate legacy API key requires user ID
+    if (method.type === 'legacy-api-key' && !this.config.userId) {
+      return {
+        success: false,
+        error: 'Legacy API key authentication requires both apiKey and userId',
+      }
+    }
+
+    return {
+      success: true,
+      method,
+    }
+  }
+
+  private setupInterceptors(): void {
+    this.client.interceptors.response.use(
+      (response: AxiosResponse) => response,
+      error => {
+        if (axios.isAxiosError(error)) {
+          const authMethod = this.getAuthenticationMethod()
+          const status = error.response?.status
+          const detail = error.response?.data?.detail
+          const message = error.response?.data?.message || error.message
+
+          // Handle authentication-specific errors
+          if (status === 401) {
+            if (authMethod?.type === 'database-api-key') {
+              throw new Error(
+                `Database API key authentication failed: ${this.formatErrorMessage(detail, 'Invalid, expired, or inactive API key')}`
+              )
+            } else if (authMethod?.type === 'legacy-api-key') {
+              throw new Error(
+                `Legacy API key authentication failed: ${this.formatErrorMessage(detail, 'Invalid API key or user ID')}`
+              )
+            } else if (authMethod?.type === 'clerk-jwt') {
+              throw new Error(
+                `Clerk JWT authentication failed: ${this.formatErrorMessage(detail, 'Invalid or expired token')}`
+              )
+            } else {
+              throw new Error(
+                `Authentication failed: ${this.formatErrorMessage(detail || message, 'Authentication failed')}`
+              )
+            }
+          }
+
+          // Handle subscription/permission errors
+          if (status === 403) {
+            throw new Error(
+              `Access denied: ${this.formatErrorMessage(detail, 'Insufficient permissions or subscription required')}`
+            )
+          }
+
+          // Handle rate limiting
+          if (status === 429) {
+            throw new Error(
+              `Rate limit exceeded: ${this.formatErrorMessage(detail, 'Too many requests. Please try again later.')}`
+            )
+          }
+
+          // Handle usage limit errors
+          if (detail?.includes('credits') || detail?.includes('usage')) {
+            throw new Error(
+              `Usage limit exceeded: ${this.formatErrorMessage(detail, 'Usage limit exceeded')}`
+            )
+          }
+
+          // Generic API error
+          throw new Error(
+            `API Error: ${this.formatErrorMessage(detail || message, 'Unknown API error')}`
+          )
+        }
+        throw error
+      }
+    )
+  }
+
+  protected async get<T>(url: string, config?: any): Promise<T> {
+    const response = await this.client.get<T>(url, config)
+    return response.data
+  }
+
+  /**
+   * Safely format error message to avoid [object Object]
+   */
+  private formatErrorMessage(value: any, fallback: string): string {
+    if (value && typeof value === 'object') {
+      return JSON.stringify(value)
+    }
+    return value || fallback
+  }
+
+  protected async post<T>(url: string, data?: any, config?: any): Promise<T> {
+    const response = await this.client.post<T>(url, data, config)
+    return response.data
+  }
+
+  protected async put<T>(url: string, data?: any, config?: any): Promise<T> {
+    const response = await this.client.put<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
+  }
+
+  protected buildUrl(endpoint: string): string {
+    return endpoint.startsWith('/') ? endpoint : `/${endpoint}`
+  }
+}

package/services/base/index.ts

@@ -0,0 +1 @@
+export { BaseService } from './base-service'