Function formatUserFriendlyError

src/utils/errors.ts:386–497

(
  error: unknown,
  provider: string,
  context?: ErrorFormattingContext
)

// Format an error into a user-friendly structure
export function formatUserFriendlyError(
  error: unknown,
  provider: string,
  context?: ErrorFormattingContext
): FormattedError {
  const billingUrl = PROVIDER_BILLING_URLS[provider] || null;

  // Handle our custom error types first
  if (error instanceof InsufficientCreditsError) {
    return {
      title: 'Insufficient Credits',
      message: `Your ${provider} account has insufficient credits or quota.`,
      helpUrl: billingUrl,
      suggestion: 'Add credits to your account to continue using the service.'
    };
  }

  if (error instanceof RateLimitError) {
    const retryMsg = error.retryAfter
      ? `Please wait ${error.retryAfter} seconds before retrying.`
      : 'Please wait a moment before retrying.';
    return {
      title: 'Rate Limit Exceeded',
      message: `You've made too many requests to ${provider}.`,
      helpUrl: billingUrl,
      suggestion: retryMsg
    };
  }

  if (error instanceof ServiceUnavailableError) {
    return {
      title: 'Service Unavailable',
      message: getServiceUnavailableMessage(provider, context),
      helpUrl: null,
      suggestion: 'Please try again in a few moments.'
    };
  }

  if (error instanceof AuthenticationError) {
    return {
      title: 'Authentication Failed',
      message: `Your ${provider} API key is invalid or expired.`,
      helpUrl: billingUrl,
      suggestion: 'Run `oco setup` to configure a valid API key.'
    };
  }

  if (error instanceof ModelNotFoundError) {
    return {
      title: 'Model Not Found',
      message: `The model '${error.modelName}' is not available for ${provider}.`,
      helpUrl: null,
      suggestion: 'Run `oco setup` to select a valid model.'
    };
  }

  // Detect error type from raw errors
  if (isInsufficientCreditsError(error)) {