commons-proxy 2.0.0

package/src/errors.js

@@ -0,0 +1,242 @@
+/**
+ * Custom Error Classes
+ *
+ * Provides structured error types for better error handling and classification.
+ * Replaces string-based error detection with proper error class checking.
+ */
+
+/**
+ * Base error class for CommonsProxy errors
+ */
+export class CommonsProxyError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {string} code - Error code for programmatic handling
+     * @param {boolean} retryable - Whether the error is retryable
+     * @param {Object} metadata - Additional error metadata
+     */
+    constructor(message, code, retryable = false, metadata = {}) {
+        super(message);
+        this.name = 'CommonsProxyError';
+        this.code = code;
+        this.retryable = retryable;
+        this.metadata = metadata;
+    }
+
+    /**
+     * Convert to JSON for API responses
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            ...this.metadata
+        };
+    }
+}
+
+/**
+ * Rate limit error (429 / RESOURCE_EXHAUSTED)
+ */
+export class RateLimitError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {number|null} resetMs - Time in ms until rate limit resets
+     * @param {string} accountEmail - Email of the rate-limited account
+     */
+    constructor(message, resetMs = null, accountEmail = null) {
+        super(message, 'RATE_LIMITED', true, { resetMs, accountEmail });
+        this.name = 'RateLimitError';
+        this.resetMs = resetMs;
+        this.accountEmail = accountEmail;
+    }
+}
+
+/**
+ * Authentication error (invalid credentials, token expired, etc.)
+ */
+export class AuthError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {string} accountEmail - Email of the account with auth issues
+     * @param {string} reason - Specific reason for auth failure
+     */
+    constructor(message, accountEmail = null, reason = null) {
+        super(message, 'AUTH_INVALID', false, { accountEmail, reason });
+        this.name = 'AuthError';
+        this.accountEmail = accountEmail;
+        this.reason = reason;
+    }
+}
+
+/**
+ * No accounts available error
+ */
+export class NoAccountsError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {boolean} allRateLimited - Whether all accounts are rate limited
+     */
+    constructor(message = 'No accounts available', allRateLimited = false) {
+        super(message, 'NO_ACCOUNTS', allRateLimited, { allRateLimited });
+        this.name = 'NoAccountsError';
+        this.allRateLimited = allRateLimited;
+    }
+}
+
+/**
+ * Max retries exceeded error
+ */
+export class MaxRetriesError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {number} attempts - Number of attempts made
+     */
+    constructor(message = 'Max retries exceeded', attempts = 0) {
+        super(message, 'MAX_RETRIES', false, { attempts });
+        this.name = 'MaxRetriesError';
+        this.attempts = attempts;
+    }
+}
+
+/**
+ * API error from upstream service
+ */
+export class ApiError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {number} statusCode - HTTP status code
+     * @param {string} errorType - Type of API error
+     */
+    constructor(message, statusCode = 500, errorType = 'api_error') {
+        super(message, errorType.toUpperCase(), statusCode >= 500, { statusCode, errorType });
+        this.name = 'ApiError';
+        this.statusCode = statusCode;
+        this.errorType = errorType;
+    }
+}
+
+/**
+ * Native module error (version mismatch, rebuild required)
+ */
+export class NativeModuleError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {boolean} rebuildSucceeded - Whether auto-rebuild succeeded
+     * @param {boolean} restartRequired - Whether server restart is needed
+     */
+    constructor(message, rebuildSucceeded = false, restartRequired = false) {
+        super(message, 'NATIVE_MODULE_ERROR', false, { rebuildSucceeded, restartRequired });
+        this.name = 'NativeModuleError';
+        this.rebuildSucceeded = rebuildSucceeded;
+        this.restartRequired = restartRequired;
+    }
+}
+
+/**
+ * Empty response error - thrown when API returns no content
+ * Used to trigger retry logic in streaming handler
+ */
+export class EmptyResponseError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     */
+    constructor(message = 'No content received from API') {
+        super(message, 'EMPTY_RESPONSE', true, {});
+        this.name = 'EmptyResponseError';
+    }
+}
+
+/**
+ * Capacity exhausted error - Google's model is at capacity (not user quota)
+ * Should retry on same account with shorter delay, not switch accounts immediately
+ * Different from QUOTA_EXHAUSTED which indicates user's daily/hourly limit
+ */
+export class CapacityExhaustedError extends CommonsProxyError {
+    /**
+     * @param {string} message - Error message
+     * @param {number|null} retryAfterMs - Suggested retry delay in ms
+     */
+    constructor(message = 'Model capacity exhausted', retryAfterMs = null) {
+        super(message, 'CAPACITY_EXHAUSTED', true, { retryAfterMs });
+        this.name = 'CapacityExhaustedError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+
+/**
+ * Check if an error is a rate limit error
+ * Works with both custom error classes and legacy string-based errors
+ * @param {Error} error - Error to check
+ * @returns {boolean}
+ */
+export function isRateLimitError(error) {
+    if (error instanceof RateLimitError) return true;
+    const msg = (error.message || '').toLowerCase();
+    return msg.includes('429') ||
+        msg.includes('resource_exhausted') ||
+        msg.includes('quota_exhausted') ||
+        msg.includes('rate limit');
+}
+
+/**
+ * Check if an error is an authentication error
+ * Works with both custom error classes and legacy string-based errors
+ * @param {Error} error - Error to check
+ * @returns {boolean}
+ */
+export function isAuthError(error) {
+    if (error instanceof AuthError) return true;
+    const msg = (error.message || '').toUpperCase();
+    return msg.includes('AUTH_INVALID') ||
+        msg.includes('INVALID_GRANT') ||
+        msg.includes('TOKEN REFRESH FAILED');
+}
+
+/**
+ * Check if an error is an empty response error
+ * @param {Error} error - Error to check
+ * @returns {boolean}
+ */
+export function isEmptyResponseError(error) {
+    return error instanceof EmptyResponseError ||
+        error?.name === 'EmptyResponseError';
+}
+
+/**
+ * Check if an error is a capacity exhausted error (model overload, not user quota)
+ * This is different from quota exhaustion - capacity issues are temporary infrastructure
+ * limits that should be retried on the SAME account with shorter delays
+ * @param {Error} error - Error to check
+ * @returns {boolean}
+ */
+export function isCapacityExhaustedError(error) {
+    if (error instanceof CapacityExhaustedError) return true;
+    const msg = (error.message || '').toLowerCase();
+    return msg.includes('model_capacity_exhausted') ||
+        msg.includes('capacity_exhausted') ||
+        msg.includes('model is currently overloaded') ||
+        msg.includes('service temporarily unavailable');
+}
+
+// Legacy alias for backward compatibility
+export const AntigravityError = CommonsProxyError;
+
+export default {
+    CommonsProxyError,
+    AntigravityError, // Legacy alias
+    RateLimitError,
+    AuthError,
+    NoAccountsError,
+    MaxRetriesError,
+    ApiError,
+    NativeModuleError,
+    EmptyResponseError,
+    CapacityExhaustedError,
+    isRateLimitError,
+    isAuthError,
+    isEmptyResponseError,
+    isCapacityExhaustedError
+};

package/src/fallback-config.js

@@ -0,0 +1,29 @@
+/**
+ * Model Fallback Configuration
+ *
+ * Defines fallback mappings for when a model's quota is exhausted across all accounts.
+ * Enables graceful degradation to alternative models with similar capabilities.
+ */
+
+import { MODEL_FALLBACK_MAP } from './constants.js';
+
+// Re-export for convenience
+export { MODEL_FALLBACK_MAP };
+
+/**
+ * Get fallback model for a given model ID
+ * @param {string} model - Primary model ID
+ * @returns {string|null} Fallback model ID or null if no fallback exists
+ */
+export function getFallbackModel(model) {
+    return MODEL_FALLBACK_MAP[model] || null;
+}
+
+/**
+ * Check if a model has a fallback configured
+ * @param {string} model - Model ID to check
+ * @returns {boolean} True if fallback exists
+ */
+export function hasFallback(model) {
+    return model in MODEL_FALLBACK_MAP;
+}

package/src/format/content-converter.js

@@ -0,0 +1,193 @@
+/**
+ * Content Converter
+ * Converts Anthropic message content to Google Generative AI parts format
+ */
+
+import { MIN_SIGNATURE_LENGTH, GEMINI_SKIP_SIGNATURE } from '../constants.js';
+import { getCachedSignature, getCachedSignatureFamily } from './signature-cache.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Convert Anthropic role to Google role
+ * @param {string} role - Anthropic role ('user', 'assistant')
+ * @returns {string} Google role ('user', 'model')
+ */
+export function convertRole(role) {
+    if (role === 'assistant') return 'model';
+    if (role === 'user') return 'user';
+    return 'user'; // Default to user
+}
+
+/**
+ * Convert Anthropic message content to Google Generative AI parts
+ * @param {string|Array} content - Anthropic message content
+ * @param {boolean} isClaudeModel - Whether the model is a Claude model
+ * @param {boolean} isGeminiModel - Whether the model is a Gemini model
+ * @returns {Array} Google Generative AI parts array
+ */
+export function convertContentToParts(content, isClaudeModel = false, isGeminiModel = false) {
+    if (typeof content === 'string') {
+        return [{ text: content }];
+    }
+
+    if (!Array.isArray(content)) {
+        return [{ text: String(content) }];
+    }
+
+    const parts = [];
+    const deferredInlineData = []; // Collect inlineData to add at the end (Issue #91)
+
+    for (const block of content) {
+        if (!block) continue;
+
+        if (block.type === 'text') {
+            // Skip empty text blocks - they cause API errors
+            if (block.text && block.text.trim()) {
+                parts.push({ text: block.text });
+            }
+        } else if (block.type === 'image') {
+            // Handle image content
+            if (block.source?.type === 'base64') {
+                // Base64-encoded image
+                parts.push({
+                    inlineData: {
+                        mimeType: block.source.media_type,
+                        data: block.source.data
+                    }
+                });
+            } else if (block.source?.type === 'url') {
+                // URL-referenced image
+                parts.push({
+                    fileData: {
+                        mimeType: block.source.media_type || 'image/jpeg',
+                        fileUri: block.source.url
+                    }
+                });
+            }
+        } else if (block.type === 'document') {
+            // Handle document content (e.g. PDF)
+            if (block.source?.type === 'base64') {
+                parts.push({
+                    inlineData: {
+                        mimeType: block.source.media_type,
+                        data: block.source.data
+                    }
+                });
+            } else if (block.source?.type === 'url') {
+                parts.push({
+                    fileData: {
+                        mimeType: block.source.media_type || 'application/pdf',
+                        fileUri: block.source.url
+                    }
+                });
+            }
+        } else if (block.type === 'tool_use') {
+            // Convert tool_use to functionCall (Google format)
+            // For Claude models, include the id field
+            const functionCall = {
+                name: block.name,
+                args: block.input || {}
+            };
+
+            if (isClaudeModel && block.id) {
+                functionCall.id = block.id;
+            }
+
+            // Build the part with functionCall
+            const part = { functionCall };
+
+            // For Gemini models, include thoughtSignature at the part level
+            // This is required by Gemini 3+ for tool calls to work correctly
+            if (isGeminiModel) {
+                // Priority: block.thoughtSignature > cache > GEMINI_SKIP_SIGNATURE
+                let signature = block.thoughtSignature;
+
+                if (!signature && block.id) {
+                    signature = getCachedSignature(block.id);
+                    if (signature) {
+                        logger.debug(`[ContentConverter] Restored signature from cache for: ${block.id}`);
+                    }
+                }
+
+                part.thoughtSignature = signature || GEMINI_SKIP_SIGNATURE;
+            }
+
+            parts.push(part);
+        } else if (block.type === 'tool_result') {
+            // Convert tool_result to functionResponse (Google format)
+            let responseContent = block.content;
+            let imageParts = [];
+
+            if (typeof responseContent === 'string') {
+                responseContent = { result: responseContent };
+            } else if (Array.isArray(responseContent)) {
+                // Extract images from tool results first (e.g., from Read tool reading image files)
+                for (const item of responseContent) {
+                    if (item.type === 'image' && item.source?.type === 'base64') {
+                        imageParts.push({
+                            inlineData: {
+                                mimeType: item.source.media_type,
+                                data: item.source.data
+                            }
+                        });
+                    }
+                }
+
+                // Extract text content
+                const texts = responseContent
+                    .filter(c => c.type === 'text')
+                    .map(c => c.text)
+                    .join('\n');
+                responseContent = { result: texts || (imageParts.length > 0 ? 'Image attached' : '') };
+            }
+
+            const functionResponse = {
+                name: block.tool_use_id || 'unknown',
+                response: responseContent
+            };
+
+            // For Claude models, the id field must match the tool_use_id
+            if (isClaudeModel && block.tool_use_id) {
+                functionResponse.id = block.tool_use_id;
+            }
+
+            parts.push({ functionResponse });
+
+            // Defer images from the tool result to end of parts array (Issue #91)
+            // This ensures all functionResponse parts are consecutive
+            deferredInlineData.push(...imageParts);
+        } else if (block.type === 'thinking') {
+            // Handle thinking blocks with signature compatibility check
+            if (block.signature && block.signature.length >= MIN_SIGNATURE_LENGTH) {
+                const signatureFamily = getCachedSignatureFamily(block.signature);
+                const targetFamily = isClaudeModel ? 'claude' : isGeminiModel ? 'gemini' : null;
+
+                // Drop blocks with incompatible signatures for Gemini (cross-model switch)
+                if (isGeminiModel && signatureFamily && targetFamily && signatureFamily !== targetFamily) {
+                    logger.debug(`[ContentConverter] Dropping incompatible ${signatureFamily} thinking for ${targetFamily} model`);
+                    continue;
+                }
+
+                // Drop blocks with unknown signature origin for Gemini (cold cache - safe default)
+                if (isGeminiModel && !signatureFamily && targetFamily) {
+                    logger.debug(`[ContentConverter] Dropping thinking with unknown signature origin`);
+                    continue;
+                }
+
+                // Compatible - convert to Gemini format with signature
+                parts.push({
+                    text: block.thinking,
+                    thought: true,
+                    thoughtSignature: block.signature
+                });
+            }
+            // Unsigned thinking blocks are dropped (existing behavior)
+        }
+    }
+
+    // Add deferred inlineData at the end (Issue #91)
+    // This ensures functionResponse parts are consecutive, which Claude's API requires
+    parts.push(...deferredInlineData);
+
+    return parts;
+}

package/src/format/index.js

@@ -0,0 +1,20 @@
+/**
+ * Format Converter Module
+ * Converts between Anthropic Messages API format and Google Generative AI format
+ */
+
+// Re-export all from each module
+export * from './request-converter.js';
+export * from './response-converter.js';
+export * from './content-converter.js';
+export * from './schema-sanitizer.js';
+export * from './thinking-utils.js';
+
+// Default export for backward compatibility
+import { convertAnthropicToGoogle } from './request-converter.js';
+import { convertGoogleToAnthropic } from './response-converter.js';
+
+export default {
+    convertAnthropicToGoogle,
+    convertGoogleToAnthropic
+};