testchimp-runner-core 0.0.35 → 0.0.37

package/plandocs/CREDIT_CALLBACK_ARCHITECTURE.md

@@ -1,253 +0,0 @@
-# Credit Usage Callback Architecture
-
-## Summary
-Added callback-based credit usage reporting to allow server-side integration to update DB directly without axios calls, while client-side continues using axios calls to backend API.
-
-## Architecture
-
-### Callback-First Approach
-
-```typescript
-export interface CreditUsage {
-  credits: number;
-  usageReason: CreditUsageReason;
-  jobId?: string;
-  timestamp: number;
-}
-
-export type CreditUsageCallback = (usage: CreditUsage) => void | Promise<void>;
-```
-
-### Behavior
-
-```typescript
-async reportCreditUsage(credits, usageReason, jobId) {
-  const creditUsage = { credits, usageReason, jobId, timestamp: Date.now() };
-  
-  // 1. If callback provided: Use callback (SERVER-SIDE)
-  if (this.creditUsageCallback) {
-    await this.creditUsageCallback(creditUsage);
-    return {}; // No axios call needed
-  }
-  
-  // 2. No callback but auth configured: Use axios (CLIENT-SIDE)
-  if (this.authConfig) {
-    await axios.post(`${backend}/localagent/insert_credit_usage`, ...);
-    return response.data;
-  }
-  
-  // 3. No callback and no auth: Development mode
-  return {};
-}
-```
-
-## Usage Scenarios
-
-### Server-Side (scriptservice)
-
-```typescript
-import { TestChimpService, CreditUsage, CreditUsageReason } from 'testchimp-runner-core';
-
-const service = new TestChimpService(
-  fileHandler,
-  undefined, // NO auth config
-  backendUrl,
-  maxWorkers,
-  llmProvider,
-  progressReporter,
-  orchestratorOptions,
-  async (creditUsage: CreditUsage) => {
-    // Update DB directly - NO axios calls
-    await db.insertCreditUsage({
-      credits: creditUsage.credits,
-      usageReason: creditUsage.usageReason,
-      jobId: creditUsage.jobId,
-      timestamp: creditUsage.timestamp
-    });
-  }
-);
-```
-
-**Result:**
-- ✅ Callback called → DB updated directly
-- ❌ No axios calls (no auth configured)
-- ✅ Full control over DB updates
-
-### Client-Side (vs-extension, github-action)
-
-```typescript
-import { TestChimpService } from 'testchimp-runner-core';
-
-const service = new TestChimpService(
-  fileHandler,
-  authConfig, // Auth configured
-  backendUrl,
-  maxWorkers,
-  llmProvider,
-  progressReporter,
-  orchestratorOptions
-  // NO callback - uses axios
-);
-```
-
-**Result:**
-- ❌ No callback provided
-- ✅ Axios call made to backend API (because auth configured)
-- ✅ Backend handles DB update
-
-### Development Mode (local testing)
-
-```typescript
-const service = new TestChimpService(
-  fileHandler
-  // No auth, no callback
-);
-```
-
-**Result:**
-- ❌ No callback
-- ❌ No auth
-- ⚠️ Warning logged: "Credit usage not tracked"
-- ✅ Continues without error
-
-## API
-
-### Constructor
-```typescript
-new TestChimpService(
-  fileHandler?,
-  authConfig?,
-  backendUrl?,
-  maxWorkers?,
-  llmProvider?,
-  progressReporter?,
-  orchestratorOptions?,
-  creditUsageCallback? // NEW
-)
-```
-
-### Method
-```typescript
-service.setCreditUsageCallback((creditUsage) => {
-  // Handle credit usage in your system
-  console.log(`Used ${creditUsage.credits} credits for ${creditUsage.usageReason}`);
-});
-```
-
-## Exported Types
-
-```typescript
-export {
-  CreditUsageCallback,     // Type for callback function
-  CreditUsage,             // Interface for usage data
-  CreditUsageReason        // Enum: SCRIPT_GENERATE, TEST_REPAIR, etc.
-};
-```
-
-## Benefits
-
-### For Server-Side
-1. **No Network Calls** - Direct DB updates via callback
-2. **Full Control** - Custom logic for credit tracking
-3. **Performance** - No HTTP round-trip overhead
-4. **Reliability** - No network failures
-
-### For Client-Side
-1. **Backward Compatible** - Existing code works unchanged
-2. **Centralized** - Backend API handles all credit logic
-3. **Simple** - Just configure auth, no callback needed
-
-### For Both
-1. **Flexible** - Each consumer decides how to handle credits
-2. **Testable** - Can mock callbacks easily
-3. **Observable** - Callback provides visibility into credit usage
-
-## Implementation Notes
-
-### Preservation Across Service Recreations
-
-Credit callback is stored and reapplied when services are recreated:
-
-```typescript
-// Store in TestChimpService
-private creditUsageCallback?: CreditUsageCallback;
-
-// Pass to CreditUsageService on every recreation
-this.creditUsageService = new CreditUsageService(
-  this.authConfig,
-  this.backendUrl,
-  this.creditUsageCallback  // Always preserved
-);
-```
-
-### Error Handling
-
-**Callback-based (server-side):**
-- Callback error → Throws (critical for DB updates)
-
-**Axios-based (client-side):**
-- Axios error → Throws (critical for credit tracking)
-
-**Development mode:**
-- No tracking → Logs warning, continues
-
-## Example: Server-Side Integration
-
-```typescript
-// In scriptservice
-import { TestChimpService, CreditUsage, CreditUsageReason } from 'testchimp-runner-core';
-
-class ScriptService {
-  private testChimpService: TestChimpService;
-  
-  constructor() {
-    this.testChimpService = new TestChimpService(
-      new CustomFileHandler(),
-      undefined, // No auth - server-side doesn't need it
-      'http://localhost:3000', // Internal backend URL
-      5,
-      new CustomLLMProvider(), // Server has its own LLM provider
-      customProgressReporter,
-      { useOrchestrator: true },
-      async (creditUsage: CreditUsage) => {
-        // Direct DB update - no HTTP calls
-        await this.creditRepository.insert({
-          userId: this.getCurrentUserId(),
-          credits: creditUsage.credits,
-          reason: creditUsage.usageReason,
-          jobId: creditUsage.jobId,
-          timestamp: new Date(creditUsage.timestamp)
-        });
-      }
-    );
-  }
-}
-```
-
-## Files Modified
-
-1. `/src/credit-usage-service.ts` - Added callback support, callback-first logic
-2. `/src/index.ts` - Accept credit callback in constructor, expose `setCreditUsageCallback()`, preserve across recreations
-3. Exported types: `CreditUsage`, `CreditUsageCallback`, `CreditUsageReason`
-
-## Testing
-
-### Server-Side
-1. Set credit callback
-2. Generate script
-3. Verify callback called with correct credit data
-4. Verify NO axios calls made
-
-### Client-Side
-1. Configure auth (no callback)
-2. Generate script
-3. Verify axios call made to backend
-4. Verify backend receives credit data
-
-## Backward Compatibility
-
-✅ Fully backward compatible
-- Existing consumers work unchanged
-- Optional callback parameter
-- Existing axios behavior preserved for client-side
-