CapaKraken/packages/api/src/ai-client.ts

import { DEFAULT_OPENAI_MODEL } from "@capakraken/shared";
import OpenAI, { AzureOpenAI } from "openai";
import { logger } from "./lib/logger.js";
import { resolveSystemSettingsRuntime } from "./lib/system-settings-runtime.js";

type AiSettings = {
  aiProvider?: string | null;
  azureOpenAiEndpoint?: string | null;
  azureOpenAiDeployment?: string | null;
  azureOpenAiApiKey?: string | null;
  azureApiVersion?: string | null;
  aiMaxCompletionTokens?: number | null;
  aiTemperature?: number | null;
  azureDalleDeployment?: string | null;
  azureDalleEndpoint?: string | null;
  azureDalleApiKey?: string | null;
};

function redactDiagnosticText(value: string): string {
  return value
    .replace(/https?:\/\/[^\s)\]}]+/gi, "<redacted-url>")
    .replace(/\bsk-[A-Za-z0-9_-]+\b/g, "<redacted-secret>")
    .replace(/\bAIza[0-9A-Za-z_-]+\b/g, "<redacted-secret>")
    .replace(/(api[-_ ]?key\s*[=:]\s*)([^,\s]+)/gi, "$1<redacted-secret>")
    .replace(/(Bearer\s+)([^\s]+)/gi, "$1<redacted-secret>")
    .replace(/([?&](?:api-key|key)=)([^&\s]+)/gi, "$1<redacted-secret>");
}

export function sanitizeDiagnosticError(err: unknown): string {
  const raw = err instanceof Error ? err.message : String(err);
  return redactDiagnosticText(raw.replace(/^Error:\s*/, "")).slice(0, 300);
}

/** Returns true if the settings have enough information to make an API call. */
export function isAiConfigured(settings: AiSettings | null | undefined): boolean {
  const runtimeSettings = resolveSystemSettingsRuntime(settings);
  if (!runtimeSettings.azureOpenAiApiKey || !runtimeSettings.azureOpenAiDeployment) return false;
  if (runtimeSettings.aiProvider === "azure" && !runtimeSettings.azureOpenAiEndpoint) return false;
  return true;
}

/** Instantiates the right OpenAI client based on the stored provider setting. */
export function createAiClient(settings: AiSettings): OpenAI {
  const runtimeSettings = resolveSystemSettingsRuntime(settings);
  if (runtimeSettings.aiProvider === "azure") {
    return new AzureOpenAI({
      endpoint: runtimeSettings.azureOpenAiEndpoint!,
      apiKey: runtimeSettings.azureOpenAiApiKey!,
      apiVersion: runtimeSettings.azureApiVersion ?? "2025-01-01-preview",
      deployment: runtimeSettings.azureOpenAiDeployment!,
    });
  }
  // Default: regular OpenAI (sk-... key)
  return new OpenAI({ apiKey: runtimeSettings.azureOpenAiApiKey! });
}

/** Returns true if DALL-E image generation is configured. */
export function isDalleConfigured(settings: AiSettings | null | undefined): boolean {
  if (!settings) return false;
  const runtimeSettings = resolveSystemSettingsRuntime(settings);
  // DALL-E needs its own deployment (or a non-Azure key with model name)
  if (runtimeSettings.aiProvider === "azure") {
    return !!(runtimeSettings.azureDalleDeployment && (runtimeSettings.azureDalleEndpoint || runtimeSettings.azureOpenAiEndpoint) && (runtimeSettings.azureDalleApiKey || runtimeSettings.azureOpenAiApiKey));
  }
  // For direct OpenAI, the chat API key works for DALL-E too
  return !!runtimeSettings.azureOpenAiApiKey;
}

/** Creates an OpenAI client configured for DALL-E image generation. */
export function createDalleClient(settings: AiSettings): OpenAI {
  const runtimeSettings = resolveSystemSettingsRuntime(settings);
  if (runtimeSettings.aiProvider === "azure") {
    const endpoint = runtimeSettings.azureDalleEndpoint || runtimeSettings.azureOpenAiEndpoint!;
    const apiKey = runtimeSettings.azureDalleApiKey || runtimeSettings.azureOpenAiApiKey!;
    return new AzureOpenAI({
      endpoint,
      apiKey,
      apiVersion: runtimeSettings.azureApiVersion ?? "2025-01-01-preview",
      deployment: runtimeSettings.azureDalleDeployment!,
    });
  }
  return new OpenAI({ apiKey: runtimeSettings.azureOpenAiApiKey! });
}

/**
 * Wraps an external AI API call with timing and structured logging.
 * Use this around any chat.completions.create / images.generate / responses.create call.
 */
export async function loggedAiCall<T>(
  provider: string,
  model: string,
  promptLength: number,
  fn: () => Promise<T>,
): Promise<T> {
  const start = performance.now();
  try {
    const result = await fn();
    const responseTimeMs = Math.round(performance.now() - start);
    logger.info({ provider, model, promptLength, responseTimeMs }, "External API call");
    return result;
  } catch (err) {
    const responseTimeMs = Math.round(performance.now() - start);
    const errorMessage = sanitizeDiagnosticError(err);
    logger.warn({ provider, model, promptLength, responseTimeMs, errorMessage }, "External API call failed");
    throw err;
  }
}

/** Turns raw API errors into actionable human-readable messages. */
export function parseAiError(err: unknown): string {
  const msg = err instanceof Error ? err.message : String(err);
  const lower = msg.toLowerCase();

  if (lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid_api_key") || lower.includes("incorrect api key")) {
    return "Invalid API key — make sure you copied it correctly from your provider's dashboard.";
  }
  if (lower.includes("insufficient_quota") || lower.includes("exceeded your current quota") || lower.includes("billing")) {
    return "Account quota exceeded or billing issue — check your usage limits at platform.openai.com.";
  }
  if (lower.includes("403") || lower.includes("forbidden")) {
    return "Access denied — your key may not have permission to use this model/deployment.";
  }
  if (lower.includes("deploymentnotfound") || lower.includes("model_not_found") || (lower.includes("404") && lower.includes("deployment"))) {
    return "Deployment not found — check the deployment name matches exactly what's configured in Azure.";
  }
  if (lower.includes("404") || lower.includes("not found")) {
    return `Model not found — verify the model name (e.g. ${DEFAULT_OPENAI_MODEL}) is correct and available on your account.`;
  }
  if (lower.includes("429") || lower.includes("rate limit") || lower.includes("ratelimiterror")) {
    return "Rate limit exceeded — wait a moment and try again.";
  }
  if (lower.includes("econnrefused") || lower.includes("enotfound") || lower.includes("fetch failed") || lower.includes("failed to fetch")) {
    return "Cannot reach the API endpoint — check the endpoint URL and your network connection.";
  }
  if (lower.includes("context_length_exceeded") || lower.includes("maximum context")) {
    return "Request too large — the prompt exceeded the model's context limit.";
  }
  return sanitizeDiagnosticError(msg);
}