<?php
if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

/**
 * PufferGo API Exception - 自定义异常类
 * 
 * 用于携带 HTTP 状态码和操作 URL，便于前端统一处理认证/计费相关错误
 * 
 * @package PufferGo
 * @since 1.0.0
 */

class PufferGo_API_Exception extends Exception {
    
    /**
     * 控制台 / 仪表盘统一入口（主站）
     */
    const CONSOLE_BASE_URL = 'https://puffergo.com/dashboard';
    
    /**
     * 错误类型常量
     */
    const ERROR_AUTH_INVALID = 'auth_invalid';      // 401/403: API 密钥无效
    const ERROR_CREDITS_INSUFFICIENT = 'credits_insufficient'; // 402: 积分不足
    
    /**
     * 操作 URL（引导用户去解决问题）
     * @var string|null
     */
    protected $action_url = null;
    
    /**
     * 错误类型
     * @var string|null
     */
    protected $error_type = null;
    
    /**
     * 构造函数
     * 
     * @param string $message 错误消息
     * @param int $code HTTP 状态码
     * @param string|null $error_type 错误类型
     * @param string|null $action_url 操作 URL
     * @param Throwable|null $previous 前一个异常
     */
    public function __construct(
        $message = '',
        $code = 0,
        $error_type = null,
        $action_url = null,
        $previous = null
    ) {
        parent::__construct($message, $code, $previous);
        $this->error_type = $error_type;
        $this->action_url = $action_url;
    }
    
    /**
     * 获取操作 URL
     * 
     * @return string|null
     */
    public function getActionUrl() {
        return $this->action_url;
    }
    
    /**
     * 获取错误类型
     * 
     * @return string|null
     */
    public function getErrorType() {
        return $this->error_type;
    }
    
    /**
     * 创建认证错误异常（401/403）
     * 
     * @param int $code HTTP 状态码 (401 或 403)
     * @return self
     */
    public static function authInvalid($code = 401) {
        return new self(
            'API 密钥无效或已被禁用，请前往控制台重新授权',
            $code,
            self::ERROR_AUTH_INVALID,
            self::CONSOLE_BASE_URL
        );
    }
    
    /**
     * 创建积分不足异常（402）
     * 
     * @return self
     */
    public static function creditsInsufficient() {
        return new self(
            'AI 积分不足，请前往控制台升级套餐或充值',
            402,
            self::ERROR_CREDITS_INSUFFICIENT,
            self::CONSOLE_BASE_URL . '/billing'
        );
    }
    
    /**
     * 转换为数组（用于 REST API 响应）
     * 
     * @return array
     */
    public function toArray() {
        return array(
            'success' => false,
            'error_code' => $this->getCode(),
            'error_type' => $this->error_type,
            'message' => $this->getMessage(),
            'action_url' => $this->action_url,
        );
    }
}

