"""Stock data API module."""


class StockAPI:
    """Access individual stock data (basic/standard tier).

    Available via ``client.stock``.
    """

    def __init__(self, client):
        self._request = client._request

    # --- Basic tier ---

    def list(self, page: int = None, per_page: int = None,
             industry: str = None, market: str = None) -> dict:
        """Get paginated stock list with optional filters.

        Args:
            page: Page number (default 1).
            per_page: Items per page (default 50).
            industry: Industry filter.
            market: Market filter (主板/创业板/科创板).
        """
        return self._request("GET", "/api/stock/list", params={
            "page": page, "per_page": per_page,
            "industry": industry, "market": market,
        })

    def search(self, q: str) -> dict:
        """Search stocks by keyword (code, name, pinyin). Returns all results.

        Args:
            q: Search keyword.
        """
        return self._request("GET", "/api/stock/search", params={
            "q": q,
        })

    def basic(self, ts_code: str) -> dict:
        """Get stock basic info (name, industry, market cap, etc.).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
        """
        return self._request("GET", f"/api/stock/{ts_code}/basic")

    def daily(self, ts_code: str, start_date: str = None,
              end_date: str = None) -> dict:
        """Get historical daily OHLCV data.

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to 1 year ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/daily", params={
            "start_date": start_date, "end_date": end_date,
        })

    def price(self, ts_code: str) -> dict:
        """Get latest price snapshot.

        Args:
            ts_code: Stock code.
        """
        return self._request("GET", f"/api/stock/{ts_code}/price")

    def kline(self, ts_code: str, freq: str = "daily",
              start_date: str = None, end_date: str = None) -> dict:
        """Get K-line (candlestick) data at any frequency.

        Unified endpoint for daily, weekly, and monthly OHLCV data.

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            freq: Data frequency — ``daily``, ``weekly``, or ``monthly``.
            start_date: Start date (YYYYMMDD). Defaults to 1 year ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/kline", params={
            "freq": freq, "start_date": start_date,
            "end_date": end_date,
        })

    # --- Standard tier ---

    def indicators(self, ts_code: str, start_date: str = None,
                   end_date: str = None) -> dict:
        """Get technical indicators (MA, MACD, RSI, KDJ, Bollinger Bands).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to 120 days ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/indicators", params={
            "start_date": start_date, "end_date": end_date,
        })

    def factors(self, ts_code: str, start_date: str = None,
                end_date: str = None) -> dict:
        """Get multi-factor data (value, momentum, quality, volatility).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/factors", params={
            "start_date": start_date, "end_date": end_date,
        })

    # --- Structured financial data (basic tier) ---

    def block_trades(self, ts_code: str, start_date: str = None,
                     end_date: str = None) -> dict:
        """Get block trade records.

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/block-trades", params={
            "start_date": start_date, "end_date": end_date,
        })

    def express(self, ts_code: str, start_date: str = None,
                end_date: str = None) -> dict:
        """Get earnings express (业绩快报) data.

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/express", params={
            "start_date": start_date, "end_date": end_date,
        })

    def share_float(self, ts_code: str, start_date: str = None,
                    end_date: str = None) -> dict:
        """Get share float / lock-up expiry (限售解禁) data.

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/share-float", params={
            "start_date": start_date, "end_date": end_date,
        })

    def holdertrade(self, ts_code: str, start_date: str = None,
                    end_date: str = None) -> dict:
        """Get shareholder trading (股东增减持) records.

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/holdertrade", params={
            "start_date": start_date, "end_date": end_date,
        })

    def moneyflow(self, ts_code: str, start_date: str = None,
                  end_date: str = None) -> dict:
        """Get money flow data (资金流向).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to 60 days ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/moneyflow", params={
            "start_date": start_date, "end_date": end_date,
        })

    def margin(self, ts_code: str, start_date: str = None,
               end_date: str = None) -> dict:
        """Get margin trading data (融资融券).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to 60 days ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/margin", params={
            "start_date": start_date, "end_date": end_date,
        })

    def adj_factor(self, ts_code: str, start_date: str = None,
                   end_date: str = None) -> dict:
        """Get adjustment factor (复权因子).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to 250 days ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/adj-factor", params={
            "start_date": start_date, "end_date": end_date,
        })

    def stk_limit(self, ts_code: str, start_date: str = None,
                  end_date: str = None) -> dict:
        """Get daily price limits (涨跌停价格).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to 60 days ago.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/stk-limit", params={
            "start_date": start_date, "end_date": end_date,
        })

    def income(self, ts_code: str, start_date: str = None,
               end_date: str = None) -> dict:
        """Get income statement (利润表).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Report period start (YYYYMMDD). Defaults to server default.
            end_date: Report period end (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/income", params={
            "start_date": start_date, "end_date": end_date,
        })

    def balancesheet(self, ts_code: str, start_date: str = None,
                     end_date: str = None) -> dict:
        """Get balance sheet (资产负债表).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Report period start (YYYYMMDD). Defaults to server default.
            end_date: Report period end (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/balancesheet", params={
            "start_date": start_date, "end_date": end_date,
        })

    def cashflow(self, ts_code: str, start_date: str = None,
                 end_date: str = None) -> dict:
        """Get cash flow statement (现金流量表).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Report period start (YYYYMMDD). Defaults to server default.
            end_date: Report period end (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/cashflow", params={
            "start_date": start_date, "end_date": end_date,
        })

    def holdernumber(self, ts_code: str, start_date: str = None,
                     end_date: str = None) -> dict:
        """Get shareholder count changes (股东人数).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/holdernumber", params={
            "start_date": start_date, "end_date": end_date,
        })

    def dividend(self, ts_code: str, start_date: str = None,
                 end_date: str = None) -> dict:
        """Get dividend records (分红送股).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/dividend", params={
            "start_date": start_date, "end_date": end_date,
        })

    def suspend(self, ts_code: str, start_date: str = None,
                end_date: str = None) -> dict:
        """Get trading suspension records (停复牌).

        Args:
            ts_code: Stock code, e.g. ``000001.SZ``.
            start_date: Start date (YYYYMMDD). Defaults to server default.
            end_date: End date (YYYYMMDD). Defaults to today.
        """
        return self._request("GET", f"/api/stock/{ts_code}/suspend", params={
            "start_date": start_date, "end_date": end_date,
        })
