settfex 0.1.0__py3-none-any.whl

settfex/services/set/stock/board_of_director.py

@@ -0,0 +1,240 @@
+"""SET Board of Director Service - Fetch board of directors for individual stock symbols."""
+
+from typing import Any
+
+from loguru import logger
+from pydantic import BaseModel, ConfigDict, Field
+
+from settfex.services.set.constants import SET_BASE_URL, SET_BOARD_OF_DIRECTOR_ENDPOINT
+from settfex.services.set.stock.utils import normalize_language, normalize_symbol
+from settfex.utils.data_fetcher import AsyncDataFetcher, FetcherConfig
+
+
+class Director(BaseModel):
+    """Model for individual board member/director information."""
+
+    name: str = Field(description="Director's full name")
+    positions: list[str] = Field(description="List of positions held by the director")
+
+    model_config = ConfigDict(
+        str_strip_whitespace=True,  # Strip whitespace from strings
+    )
+
+
+class BoardOfDirectorService:
+    """
+    Service for fetching board of directors data from SET API.
+
+    This service provides async methods to fetch board of directors and management
+    information for individual stock symbols from the Stock Exchange of Thailand (SET).
+    """
+
+    def __init__(self, config: FetcherConfig | None = None) -> None:
+        """
+        Initialize the board of director service.
+
+        Args:
+            config: Optional fetcher configuration (uses defaults if None)
+
+        Example:
+            >>> # Default: Uses SessionManager for automatic cookie handling
+            >>> service = BoardOfDirectorService()
+        """
+        self.config = config or FetcherConfig()
+        self.base_url = SET_BASE_URL
+        logger.info(f"BoardOfDirectorService initialized with base_url={self.base_url}")
+
+    async def fetch_board_of_directors(
+        self, symbol: str, lang: str = "en"
+    ) -> list[Director]:
+        """
+        Fetch board of directors for a specific stock symbol.
+
+        Args:
+            symbol: Stock symbol (e.g., "CPALL", "PTT", "mint")
+            lang: Language for response ('en' or 'th', default: 'en')
+
+        Returns:
+            List of Director objects containing name and positions
+
+        Raises:
+            ValueError: If symbol is empty or language is invalid
+            Exception: If request fails or response cannot be parsed
+
+        Example:
+            >>> service = BoardOfDirectorService()
+            >>> directors = await service.fetch_board_of_directors("MINT", lang="en")
+            >>> for director in directors:
+            ...     print(f"{director.name}: {', '.join(director.positions)}")
+        """
+        # Normalize and validate inputs
+        symbol = normalize_symbol(symbol)
+        lang = normalize_language(lang)
+
+        if not symbol:
+            error_msg = "Stock symbol cannot be empty"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        # Build URL with symbol and language parameters
+        endpoint = SET_BOARD_OF_DIRECTOR_ENDPOINT.format(symbol=symbol)
+        url = f"{self.base_url}{endpoint}?lang={lang}"
+
+        logger.info(
+            f"Fetching board of directors for symbol '{symbol}' (lang={lang}) from {url}"
+        )
+
+        async with AsyncDataFetcher(config=self.config) as fetcher:
+            # Get optimized headers for SET API with symbol-specific referer
+            # This is critical for bypassing Incapsula bot detection
+            referer = f"https://www.set.or.th/en/market/product/stock/quote/{symbol}/overview"
+            headers = AsyncDataFetcher.get_set_api_headers(referer=referer)
+
+            # Fetch raw response - SessionManager handles cookies automatically
+            response = await fetcher.fetch(url, headers=headers)
+
+            # Check for errors
+            if response.status_code != 200:
+                error_msg = (
+                    f"Failed to fetch board of directors for {symbol}: "
+                    f"HTTP {response.status_code}"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg)
+
+            # Parse JSON
+            import json
+
+            try:
+                data = json.loads(response.text)
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse JSON response: {e}")
+                logger.debug(f"Response text: {response.text[:500]}")
+                raise
+
+            # Validate that data is a list
+            if not isinstance(data, list):
+                error_msg = (
+                    f"Expected list response but got {type(data).__name__}: "
+                    f"{str(data)[:200]}"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg)
+
+            # Parse and validate response using Pydantic
+            directors = [Director(**director_data) for director_data in data]
+
+            logger.info(
+                f"Successfully fetched {len(directors)} board members for {symbol}"
+            )
+
+            return directors
+
+    async def fetch_board_of_directors_raw(
+        self, symbol: str, lang: str = "en"
+    ) -> list[dict[str, Any]]:
+        """
+        Fetch board of directors as raw list of dictionaries without Pydantic validation.
+
+        Useful for debugging or when you need the raw API response.
+
+        Args:
+            symbol: Stock symbol (e.g., "CPALL", "PTT", "mint")
+            lang: Language for response ('en' or 'th', default: 'en')
+
+        Returns:
+            Raw list of dictionaries from API
+
+        Raises:
+            ValueError: If symbol is empty or language is invalid
+            Exception: If request fails
+
+        Example:
+            >>> service = BoardOfDirectorService()
+            >>> raw_data = await service.fetch_board_of_directors_raw("MINT")
+            >>> print(f"Found {len(raw_data)} directors")
+            >>> print(raw_data[0].keys())
+        """
+        # Normalize and validate inputs
+        symbol = normalize_symbol(symbol)
+        lang = normalize_language(lang)
+
+        if not symbol:
+            error_msg = "Stock symbol cannot be empty"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        # Build URL with symbol and language parameters
+        endpoint = SET_BOARD_OF_DIRECTOR_ENDPOINT.format(symbol=symbol)
+        url = f"{self.base_url}{endpoint}?lang={lang}"
+
+        logger.info(
+            f"Fetching raw board of directors for '{symbol}' (lang={lang}) from {url}"
+        )
+
+        async with AsyncDataFetcher(config=self.config) as fetcher:
+            # Get optimized headers for SET API with symbol-specific referer
+            referer = f"https://www.set.or.th/en/market/product/stock/quote/{symbol}/overview"
+            headers = AsyncDataFetcher.get_set_api_headers(referer=referer)
+
+            # Fetch raw response - SessionManager handles cookies automatically
+            response = await fetcher.fetch(url, headers=headers)
+
+            # Check for errors
+            if response.status_code != 200:
+                error_msg = (
+                    f"Failed to fetch board of directors for {symbol}: "
+                    f"HTTP {response.status_code}"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg)
+
+            # Parse JSON
+            import json
+
+            try:
+                data = json.loads(response.text)
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse JSON response: {e}")
+                logger.debug(f"Response text: {response.text[:500]}")
+                raise
+
+            # Validate that data is a list
+            if not isinstance(data, list):
+                error_msg = (
+                    f"Expected list response but got {type(data).__name__}: "
+                    f"{str(data)[:200]}"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg)
+
+            logger.debug(f"Raw response: {len(data)} directors")
+            return data
+
+
+# Convenience function for quick access
+async def get_board_of_directors(
+    symbol: str,
+    lang: str = "en",
+    config: FetcherConfig | None = None,
+) -> list[Director]:
+    """
+    Convenience function to fetch board of directors.
+
+    Args:
+        symbol: Stock symbol (e.g., "CPALL", "PTT", "mint")
+        lang: Language for response ('en' or 'th', default: 'en')
+        config: Optional fetcher configuration
+
+    Returns:
+        List of Director objects with name and positions
+
+    Example:
+        >>> from settfex.services.set.stock import get_board_of_directors
+        >>> # Uses SessionManager for automatic cookie handling
+        >>> directors = await get_board_of_directors("MINT")
+        >>> for director in directors[:5]:
+        ...     print(f"{director.name}: {', '.join(director.positions)}")
+    """
+    service = BoardOfDirectorService(config=config)
+    return await service.fetch_board_of_directors(symbol=symbol, lang=lang)

settfex/services/set/stock/corporate_action.py

@@ -0,0 +1,310 @@
+"""SET Stock Corporate Action Service - Fetch corporate action data for stock symbols."""
+
+from datetime import datetime
+from typing import Any
+
+from loguru import logger
+from pydantic import BaseModel, ConfigDict, Field
+
+from settfex.services.set.constants import SET_BASE_URL, SET_CORPORATE_ACTION_ENDPOINT
+from settfex.services.set.stock.utils import normalize_language, normalize_symbol
+from settfex.utils.data_fetcher import AsyncDataFetcher, FetcherConfig
+
+
+class CorporateAction(BaseModel):
+    """Model for individual corporate action."""
+
+    symbol: str = Field(description="Stock symbol/ticker")
+    name: str = Field(description="Company name (may be empty)")
+    ca_type: str = Field(alias="caType", description="Corporate action type (e.g., XD, XM)")
+    type: str = Field(description="Action type")
+
+    # Common fields
+    book_close_date: datetime | None = Field(
+        default=None, alias="bookCloseDate", description="Book closure date"
+    )
+    record_date: datetime | None = Field(
+        default=None, alias="recordDate", description="Record date"
+    )
+    remark: str | None = Field(default=None, description="Additional remarks or notes")
+    x_date: datetime | None = Field(
+        default=None, alias="xdate", description="Ex-date (ex-dividend or ex-rights)"
+    )
+    x_session: str | None = Field(default=None, alias="xSession", description="Ex-date session")
+
+    # Dividend-specific fields (XD type)
+    payment_date: datetime | None = Field(
+        default=None, alias="paymentDate", description="Dividend payment date"
+    )
+    begin_operation: datetime | None = Field(
+        default=None, alias="beginOperation", description="Operation period start date"
+    )
+    end_operation: datetime | None = Field(
+        default=None, alias="endOperation", description="Operation period end date"
+    )
+    source_of_dividend: str | None = Field(
+        default=None, alias="sourceOfDividend", description="Source of dividend (e.g., Net Profit)"
+    )
+    dividend: float | None = Field(default=None, description="Dividend amount per share")
+    currency: str | None = Field(default=None, description="Currency code (e.g., Baht)")
+    ratio: str | None = Field(default=None, description="Dividend ratio (e.g., '15 : 1')")
+    dividend_type: str | None = Field(
+        default=None, alias="dividendType", description="Type of dividend (e.g., Cash Dividend)"
+    )
+    approximate_payment_date: datetime | None = Field(
+        default=None, alias="approximatePaymentDate", description="Approximate payment date"
+    )
+    tentative_dividend_flag: bool | None = Field(
+        default=None, alias="tentativeDividendFlag", description="Flag for tentative dividend"
+    )
+    tentative_dividend: float | None = Field(
+        default=None, alias="tentativeDividend", description="Tentative dividend amount"
+    )
+    dividend_payment: str | None = Field(
+        default=None, alias="dividendPayment", description="Dividend payment amount as string"
+    )
+
+    # Meeting-specific fields (XM type)
+    meeting_date: datetime | None = Field(
+        default=None, alias="meetingDate", description="Meeting date and time"
+    )
+    agenda: str | None = Field(default=None, description="Meeting agenda items")
+    venue: str | None = Field(default=None, description="Meeting venue location")
+    meeting_type: str | None = Field(
+        default=None, alias="meetingType", description="Type of meeting (e.g., AGM, EGM)"
+    )
+    inquiry_date: datetime | None = Field(
+        default=None, alias="inquiryDate", description="Inquiry date"
+    )
+
+    model_config = ConfigDict(
+        populate_by_name=True,  # Allow both field name and alias
+        str_strip_whitespace=True,  # Strip whitespace from strings
+    )
+
+
+class CorporateActionService:
+    """
+    Service for fetching corporate action data from SET API.
+
+    This service provides async methods to fetch corporate action data for individual
+    stock symbols from the Stock Exchange of Thailand (SET), including dividend
+    announcements (XD), shareholder meetings (XM), and other corporate events.
+    """
+
+    def __init__(self, config: FetcherConfig | None = None) -> None:
+        """
+        Initialize the corporate action service.
+
+        Args:
+            config: Optional fetcher configuration (uses defaults if None)
+
+        Example:
+            >>> # Default: Uses SessionManager for automatic cookie handling
+            >>> service = CorporateActionService()
+        """
+        self.config = config or FetcherConfig()
+        self.base_url = SET_BASE_URL
+        logger.info(f"CorporateActionService initialized with base_url={self.base_url}")
+
+    async def fetch_corporate_actions(
+        self, symbol: str, lang: str = "en"
+    ) -> list[CorporateAction]:
+        """
+        Fetch corporate actions for a specific stock symbol.
+
+        Args:
+            symbol: Stock symbol (e.g., "AOT", "PTT", "cpall")
+            lang: Language for response ('en' or 'th', default: 'en')
+
+        Returns:
+            List of CorporateAction objects with corporate action data
+
+        Raises:
+            ValueError: If symbol is empty or language is invalid
+            Exception: If request fails or response cannot be parsed
+
+        Example:
+            >>> service = CorporateActionService()
+            >>> actions = await service.fetch_corporate_actions("AOT", lang="en")
+            >>> for action in actions:
+            ...     if action.ca_type == "XD":
+            ...         print(f"Dividend: {action.dividend} {action.currency}")
+            ...         print(f"XD Date: {action.x_date}")
+            ...     elif action.ca_type == "XM":
+            ...         print(f"Meeting: {action.meeting_type}")
+            ...         print(f"Agenda: {action.agenda}")
+        """
+        # Normalize and validate inputs
+        symbol = normalize_symbol(symbol)
+        lang = normalize_language(lang)
+
+        if not symbol:
+            error_msg = "Stock symbol cannot be empty"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        # Build URL with symbol and language parameters
+        endpoint = SET_CORPORATE_ACTION_ENDPOINT.format(symbol=symbol)
+        url = f"{self.base_url}{endpoint}?lang={lang}"
+
+        logger.info(f"Fetching corporate actions for symbol '{symbol}' (lang={lang}) from {url}")
+
+        async with AsyncDataFetcher(config=self.config) as fetcher:
+            # Get optimized headers for SET API with symbol-specific referer
+            # This is critical for bypassing Incapsula bot detection
+            referer = f"https://www.set.or.th/en/market/product/stock/quote/{symbol}/overview"
+            headers = AsyncDataFetcher.get_set_api_headers(referer=referer)
+
+            # Fetch raw response - SessionManager handles cookies automatically
+            response = await fetcher.fetch(url, headers=headers)
+
+            # Check for errors
+            if response.status_code != 200:
+                error_msg = (
+                    f"Failed to fetch corporate actions for {symbol}: "
+                    f"HTTP {response.status_code}"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg)
+
+            # Parse JSON
+            import json
+
+            try:
+                data = json.loads(response.text)
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse JSON response: {e}")
+                logger.debug(f"Response text: {response.text[:500]}")
+                raise
+
+            # Data should be a list
+            if not isinstance(data, list):
+                error_msg = f"Expected list response, got {type(data).__name__}"
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+
+            # Parse and validate each corporate action using Pydantic
+            corporate_actions = [CorporateAction(**item) for item in data]
+
+            logger.info(
+                f"Successfully fetched {len(corporate_actions)} corporate action(s) for {symbol}"
+            )
+
+            # Log summary by type
+            type_counts: dict[str, int] = {}
+            for action in corporate_actions:
+                type_counts[action.ca_type] = type_counts.get(action.ca_type, 0) + 1
+
+            if type_counts:
+                summary = ", ".join([f"{k}={v}" for k, v in type_counts.items()])
+                logger.debug(f"Corporate action summary for {symbol}: {summary}")
+
+            return corporate_actions
+
+    async def fetch_corporate_actions_raw(
+        self, symbol: str, lang: str = "en"
+    ) -> list[dict[str, Any]]:
+        """
+        Fetch corporate actions as raw list of dictionaries without Pydantic validation.
+
+        Useful for debugging or when you need the raw API response.
+
+        Args:
+            symbol: Stock symbol (e.g., "AOT", "PTT", "cpall")
+            lang: Language for response ('en' or 'th', default: 'en')
+
+        Returns:
+            Raw list of dictionaries from API
+
+        Raises:
+            ValueError: If symbol is empty or language is invalid
+            Exception: If request fails
+
+        Example:
+            >>> service = CorporateActionService()
+            >>> raw_data = await service.fetch_corporate_actions_raw("AOT")
+            >>> print(f"Found {len(raw_data)} actions")
+            >>> for action in raw_data:
+            ...     print(action.keys())
+        """
+        # Normalize and validate inputs
+        symbol = normalize_symbol(symbol)
+        lang = normalize_language(lang)
+
+        if not symbol:
+            error_msg = "Stock symbol cannot be empty"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        # Build URL with symbol and language parameters
+        endpoint = SET_CORPORATE_ACTION_ENDPOINT.format(symbol=symbol)
+        url = f"{self.base_url}{endpoint}?lang={lang}"
+
+        logger.info(
+            f"Fetching raw corporate actions for '{symbol}' (lang={lang}) from {url}"
+        )
+
+        async with AsyncDataFetcher(config=self.config) as fetcher:
+            # Get optimized headers for SET API with symbol-specific referer
+            referer = f"https://www.set.or.th/en/market/product/stock/quote/{symbol}/overview"
+            headers = AsyncDataFetcher.get_set_api_headers(referer=referer)
+
+            # Fetch raw response - SessionManager handles cookies automatically
+            response = await fetcher.fetch(url, headers=headers)
+
+            # Check for errors
+            if response.status_code != 200:
+                error_msg = (
+                    f"Failed to fetch corporate actions for {symbol}: "
+                    f"HTTP {response.status_code}"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg)
+
+            # Parse JSON
+            import json
+
+            try:
+                data = json.loads(response.text)
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse JSON response: {e}")
+                logger.debug(f"Response text: {response.text[:500]}")
+                raise
+
+            # Data should be a list
+            if not isinstance(data, list):
+                error_msg = f"Expected list response, got {type(data).__name__}"
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+
+            logger.debug(f"Raw response contains {len(data)} corporate action(s)")
+            return data
+
+
+# Convenience function for quick access
+async def get_corporate_actions(
+    symbol: str,
+    lang: str = "en",
+    config: FetcherConfig | None = None,
+) -> list[CorporateAction]:
+    """
+    Convenience function to fetch corporate action data.
+
+    Args:
+        symbol: Stock symbol (e.g., "AOT", "PTT", "cpall")
+        lang: Language for response ('en' or 'th', default: 'en')
+        config: Optional fetcher configuration
+
+    Returns:
+        List of CorporateAction objects with corporate action data
+
+    Example:
+        >>> from settfex.services.set.stock import get_corporate_actions
+        >>> # Uses SessionManager for automatic cookie handling
+        >>> actions = await get_corporate_actions("AOT")
+        >>> for action in actions:
+        ...     print(f"{action.ca_type}: {action.x_date}")
+    """
+    service = CorporateActionService(config=config)
+    return await service.fetch_corporate_actions(symbol=symbol, lang=lang)

settfex/services/set/stock/financial/__init__.py

@@ -0,0 +1,25 @@
+"""Financial services for fetching balance sheet, income statement, and cash flow data."""
+
+from settfex.services.set.stock.financial.financial import (
+    Account,
+    BalanceSheet,
+    CashFlow,
+    FinancialService,
+    FinancialStatement,
+    IncomeStatement,
+    get_balance_sheet,
+    get_cash_flow,
+    get_income_statement,
+)
+
+__all__ = [
+    "Account",
+    "FinancialStatement",
+    "BalanceSheet",
+    "IncomeStatement",
+    "CashFlow",
+    "FinancialService",
+    "get_balance_sheet",
+    "get_income_statement",
+    "get_cash_flow",
+]