@bobfrankston/gcards 0.1.10 → 0.1.11

package/gcards.ts

@@ -14,11 +14,22 @@ import type { GooglePerson, GoogleConnectionsResponse } from './glib/types.ts';
 import { GCARDS_GUID_KEY, extractGuids } from './glib/gctypes.ts';
 import type { ContactIndex, IndexEntry, DeletedEntry, DeleteQueue, DeleteQueueEntry, PushStatus, PendingChange, UserPaths } from './glib/gctypes.ts';
 import { DATA_DIR, CREDENTIALS_FILE, loadConfig, saveConfig, getUserPaths, ensureUserDir, loadIndex, normalizeUser, getAllUsers, resolveUser, FileLogger } from './glib/gutils.ts';
+import { explainApiError, isAIAvailable } from './glib/aihelper.ts';
 
 const PEOPLE_API_BASE = 'https://people.googleapis.com/v1';
 const CONTACTS_SCOPE_READ = 'https://www.googleapis.com/auth/contacts.readonly';
 const CONTACTS_SCOPE_WRITE = 'https://www.googleapis.com/auth/contacts';
 
+/** Custom error that includes the payload for AI analysis */
+class ApiError extends Error {
+    payload?: unknown;
+    constructor(message: string, payload?: unknown) {
+        super(message);
+        this.name = 'ApiError';
+        this.payload = payload;
+    }
+}
+
 function ts(): string {
     const now = new Date();
     return `[${now.toTimeString().slice(0, 8)}]`;
@@ -698,7 +709,7 @@ async function updateContactOnGoogle(person: GooglePerson, retryCount = 0, token
     }
 
     if (!response.ok) {
-        throw new Error(`${response.status} ${await response.text()}`);
+        throw new ApiError(`${response.status} ${await response.text()}`, person);
     }
 }
 
@@ -778,7 +789,7 @@ async function createContactOnGoogle(person: GooglePerson, retryCount = 0, token
     }
 
     if (!response.ok) {
-        throw new Error(`${response.status} ${await response.text()}`);
+        throw new ApiError(`${response.status} ${await response.text()}`, person);
     }
 
     return await response.json();
@@ -1023,6 +1034,26 @@ async function pushContacts(user: string, options: { yes: boolean; verbose: bool
             console.log(` ERROR: ${error.message}`);
             problems.push(errorMsg);
             errorCount++;
+
+            // Get AI explanation if available and error is from API
+            if (error instanceof ApiError && error.payload && isAIAvailable()) {
+                try {
+                    const explanation = await explainApiError(error.message, error.payload);
+                    if (explanation) {
+                        console.log(`\n    AI Analysis:`);
+                        if (explanation.explanation) {
+                            console.log(`      Problem: ${explanation.explanation}`);
+                        }
+                        if (explanation.suggestedFix) {
+                            console.log(`      Fix: ${explanation.suggestedFix}`);
+                        }
+                        if (explanation.correctedJson) {
+                            console.log(`      Corrected JSON:\n${explanation.correctedJson.split('\n').map(l => '        ' + l).join('\n')}`);
+                        }
+                        problems.push(`  AI: ${explanation.explanation || ''} Fix: ${explanation.suggestedFix || ''}`);
+                    }
+                } catch { /* ignore AI errors */ }
+            }
         }
     }
 

package/glib/aihelper.ts

@@ -0,0 +1,196 @@
+/**
+ * AI-powered error explanation helper for Google People API errors
+ * Uses Anthropic Claude (primary) or OpenAI (fallback)
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Load keys from standard locations (AppData for Windows, ~/.config for Unix)
+function loadEnvFile(): void {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const appData = process.env.APPDATA || path.join(home, '.config');
+
+    const locations = [
+        path.join(appData, 'gcards', 'keys.env'),  // Standard app config location
+        path.join(home, '.gcards', 'keys.env'),     // Unix dotfile style
+        path.join(process.cwd(), 'keys.env'),       // Local override (dev only)
+        path.join(process.cwd(), '.env'),
+    ];
+
+    for (const loc of locations) {
+        if (fs.existsSync(loc)) {
+            const content = fs.readFileSync(loc, 'utf-8');
+            for (const line of content.split(/\r?\n/)) {
+                const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+                if (match && !process.env[match[1]]) {
+                    process.env[match[1]] = match[2].trim().replace(/^["']|["']$/g, '');
+                }
+            }
+            break;
+        }
+    }
+}
+
+loadEnvFile();
+
+export interface AIErrorExplanation {
+    explanation: string;
+    suggestedFix: string;
+    correctedJson?: string;
+}
+
+const SYSTEM_PROMPT = `You are an expert on the Google People API for contacts. When given an API error and the JSON payload that caused it, provide:
+
+1. A brief explanation of what went wrong
+2. The specific fix needed
+3. If possible, the corrected JSON snippet
+
+Be extremely concise. No preamble. Format:
+PROBLEM: <one line>
+FIX: <one line>
+CORRECTED: <json if applicable, or "N/A">
+
+Common issues:
+- nicknames is a top-level field, NOT nested in names[]
+- phoneNumbers[].type values: "mobile", "home", "work", "homeFax", "workFax", "otherFax", "pager", "workMobile", "workPager", "main", "googleVoice", "other"
+- emailAddresses[].type values: "home", "work", "other"
+- addresses[].type values: "home", "work", "other"
+- birthdays[].date needs {year?, month, day} not a string
+- organizations[].type values: "work", "school"
+- Field names are camelCase not snake_case`;
+
+async function callAnthropic(errorMsg: string, payload: string): Promise<string | null> {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) return null;
+
+    try {
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                'anthropic-version': '2023-06-01'
+            },
+            body: JSON.stringify({
+                model: 'claude-3-haiku-20240307',
+                max_tokens: 500,
+                system: SYSTEM_PROMPT,
+                messages: [{
+                    role: 'user',
+                    content: `Error: ${errorMsg}\n\nPayload:\n${payload}`
+                }]
+            })
+        });
+
+        if (!response.ok) return null;
+
+        const data = await response.json() as any;
+        return data.content?.[0]?.text || null;
+    } catch {
+        return null;
+    }
+}
+
+async function callOpenAI(errorMsg: string, payload: string): Promise<string | null> {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) return null;
+
+    try {
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`
+            },
+            body: JSON.stringify({
+                model: 'gpt-4o-mini',
+                max_tokens: 500,
+                messages: [
+                    { role: 'system', content: SYSTEM_PROMPT },
+                    { role: 'user', content: `Error: ${errorMsg}\n\nPayload:\n${payload}` }
+                ]
+            })
+        });
+
+        if (!response.ok) return null;
+
+        const data = await response.json() as any;
+        return data.choices?.[0]?.message?.content || null;
+    } catch {
+        return null;
+    }
+}
+
+function parseAIResponse(response: string): AIErrorExplanation {
+    const lines = response.split('\n');
+    let explanation = '';
+    let suggestedFix = '';
+    let correctedJson: string | undefined;
+    let inCorrected = false;
+    const correctedLines: string[] = [];
+
+    for (const line of lines) {
+        if (line.startsWith('PROBLEM:')) {
+            explanation = line.substring(8).trim();
+        } else if (line.startsWith('FIX:')) {
+            suggestedFix = line.substring(4).trim();
+        } else if (line.startsWith('CORRECTED:')) {
+            const rest = line.substring(10).trim();
+            if (rest && rest !== 'N/A') {
+                inCorrected = true;
+                if (rest !== '{' && rest !== '[') {
+                    correctedLines.push(rest);
+                } else {
+                    correctedLines.push(rest);
+                }
+            }
+        } else if (inCorrected) {
+            correctedLines.push(line);
+        }
+    }
+
+    if (correctedLines.length > 0) {
+        const joined = correctedLines.join('\n').trim();
+        // Try to extract just the JSON part
+        const jsonMatch = joined.match(/(\{[\s\S]*\}|\[[\s\S]*\])/);
+        if (jsonMatch) {
+            correctedJson = jsonMatch[1];
+        } else if (joined !== 'N/A') {
+            correctedJson = joined;
+        }
+    }
+
+    return { explanation, suggestedFix, correctedJson };
+}
+
+/**
+ * Get AI-powered explanation for a Google People API error
+ * @param errorMessage The error message from the API
+ * @param payload The JSON payload that caused the error (will be truncated if too long)
+ * @returns Explanation and fix suggestion, or null if AI unavailable
+ */
+export async function explainApiError(errorMessage: string, payload: unknown): Promise<AIErrorExplanation | null> {
+    // Truncate payload to avoid huge API calls
+    let payloadStr = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+    if (payloadStr.length > 2000) {
+        payloadStr = payloadStr.substring(0, 2000) + '\n... (truncated)';
+    }
+
+    // Try Anthropic first, then OpenAI
+    let response = await callAnthropic(errorMessage, payloadStr);
+    if (!response) {
+        response = await callOpenAI(errorMessage, payloadStr);
+    }
+
+    if (!response) return null;
+
+    return parseAIResponse(response);
+}
+
+/**
+ * Check if AI error explanation is available (any API key configured)
+ */
+export function isAIAvailable(): boolean {
+    return !!(process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/gcards",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Google Contacts cleanup and management tool",
   "type": "module",
   "main": "gcards.ts",