openstockapi 0.1.0__py3-none-any.whl

openstockapi/core/models_macro.py

@@ -0,0 +1,12 @@
+from datetime import datetime
+from pydantic import BaseModel
+from typing import List, Optional
+
+class MacroIndicatorEntry(BaseModel):
+    name: str
+    year: int
+    period: str  # e.g., "Annual", "Tháng 5/2026"
+    value: Optional[float] = None
+    unit: str
+    source: Optional[str] = None
+    provider: str

openstockapi/core/models_news.py

@@ -0,0 +1,20 @@
+from datetime import datetime
+from pydantic import BaseModel
+from typing import Optional
+
+class CompanyNewsEntry(BaseModel):
+    symbol: str
+    news_id: int
+    title: str
+    publish_date: datetime
+    url: Optional[str] = None
+    summary: Optional[str] = None
+    provider: str
+
+class CompanyEventEntry(BaseModel):
+    symbol: str
+    event_id: Optional[str] = None
+    title: str
+    event_date: Optional[datetime] = None
+    details: Optional[str] = None
+    provider: str

openstockapi/core/models_trading.py

@@ -0,0 +1,39 @@
+from pydantic import BaseModel
+from datetime import datetime
+from typing import Optional
+
+class ForeignTradingEntry(BaseModel):
+    symbol: str
+    date: datetime
+    buy_volume: float
+    buy_value: float
+    sell_volume: float
+    sell_value: float
+    net_volume: float
+    net_value: float
+    provider: str
+
+class PropTradingEntry(BaseModel):
+    symbol: str
+    date: datetime
+    buy_volume: float
+    buy_value: float
+    sell_volume: float
+    sell_value: float
+    net_volume: float
+    net_value: float
+    provider: str
+
+class InsiderTradingEntry(BaseModel):
+    symbol: str
+    trader_name: str
+    position: Optional[str] = None
+    relationship: Optional[str] = None
+    action_type: str  # "Buy" or "Sell"
+    registered_volume: float
+    actual_volume: Optional[float] = None
+    trade_status: str
+    start_date: Optional[datetime] = None
+    end_date: Optional[datetime] = None
+    post_volume: float
+    provider: str

openstockapi/core/rate_limiter.py

@@ -0,0 +1,36 @@
+import time
+from openstockapi.core.types import DataTier
+from openstockapi.core.exceptions import RateLimitError
+
+# Max requests per minute
+TIER_LIMITS = {
+    DataTier.FREE: 10,
+    DataTier.PRO: 200,
+    DataTier.PREMIUM: 500,
+}
+
+class TokenBucketRateLimiter:
+    def __init__(self) -> None:
+        # Simplistic in-memory client state map: client_id -> (tokens, last_update_time)
+        self.buckets = {}
+
+    def check_limit(self, client_key: str, tier: DataTier) -> None:
+        limit = TIER_LIMITS.get(tier, 10)
+        now = time.time()
+        
+        if client_key not in self.buckets:
+            self.buckets[client_key] = (limit - 1.0, now)
+            return
+
+        tokens, last_time = self.buckets[client_key]
+        # Calculate refill
+        elapsed = now - last_time
+        refill = elapsed * (limit / 60.0)
+        new_tokens = min(limit, tokens + refill)
+
+        if new_tokens < 1.0:
+            raise RateLimitError(f"Rate limit exceeded for tier '{tier.value}'. Limit: {limit} req/min.")
+
+        self.buckets[client_key] = (new_tokens - 1.0, now)
+
+rate_limiter = TokenBucketRateLimiter()

openstockapi/core/security.py

@@ -0,0 +1,19 @@
+from openstockapi.core.exceptions import TierUpgradeRequiredError
+from openstockapi.license.session import get_current_session
+from openstockapi.core.types import DataTier
+from openstockapi.core.rate_limiter import rate_limiter
+
+def enforce_tier_and_rate_limit(required_tier: DataTier, endpoint_name: str) -> None:
+    session = get_current_session()
+    current_tier = session.tier
+
+    # 1. Enforce data classification tier
+    # Hierarchical checks: FREE = 0, PRO = 1, PREMIUM = 2
+    tier_levels = {DataTier.FREE: 0, DataTier.PRO: 1, DataTier.PREMIUM: 2}
+    
+    if tier_levels[current_tier] < tier_levels[required_tier]:
+        raise TierUpgradeRequiredError(required_tier.value, endpoint_name)
+
+    # 2. Local client-side rate limit enforcement
+    client_key = session.api_key or "anonymous"
+    rate_limiter.check_limit(client_key, current_tier)

openstockapi/core/types.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+class DataTier(str, Enum):
+    FREE = "free"
+    PRO = "pro"
+    PREMIUM = "premium"

openstockapi/core/utils.py

@@ -0,0 +1,23 @@
+import re
+from datetime import datetime
+from typing import Any
+
+def clean_symbol(symbol: str) -> str:
+    """Standardize ticker symbols to uppercase alphanumeric."""
+    return re.sub(r"[^A-Za-z0-9]", "", symbol).upper()
+
+def parse_date(date_val: Any) -> datetime:
+    """Parse common date inputs into datetime objects."""
+    if isinstance(date_val, datetime):
+        return date_val
+    if isinstance(date_val, (int, float)):
+        return datetime.fromtimestamp(date_val)
+    if isinstance(date_val, str):
+        # Remove timezone offsets or fractional seconds if they complicate standard patterns
+        cleaned = date_val.split('.')[0]
+        for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y%m%d"):
+            try:
+                return datetime.strptime(cleaned, fmt)
+            except ValueError:
+                continue
+    raise ValueError(f"Could not parse date: {date_val}")

openstockapi/license/session.py

@@ -0,0 +1,36 @@
+import os
+from typing import Optional
+from openstockapi.core.types import DataTier
+
+class Session:
+    """Manages API key authentication and resolves the current tier."""
+    def __init__(self, api_key: Optional[str] = None) -> None:
+        self.api_key = api_key or os.getenv("OPENSTOCKAPI_KEY")
+        self.tier = self._resolve_tier()
+
+    def _resolve_tier(self) -> DataTier:
+        if not self.api_key:
+            return DataTier.FREE
+        
+        # Simple decode rule for Phase 1: check prefixes of key
+        # pro_xxx -> PRO
+        # prem_xxx -> PREMIUM
+        key = self.api_key.strip().lower()
+        if key.startswith("pro_"):
+            return DataTier.PRO
+        elif key.startswith("prem_") or key.startswith("premium_"):
+            return DataTier.PREMIUM
+        return DataTier.FREE
+
+# Default global session singleton
+_current_session = Session()
+
+def get_current_session() -> Session:
+    return _current_session
+
+def set_current_session(session: Session) -> None:
+    global _current_session
+    _current_session = session
+
+def init(api_key: str) -> None:
+    set_current_session(Session(api_key))

openstockapi/providers/__init__.py

@@ -0,0 +1,21 @@
+from openstockapi.providers.mas import MASProvider
+from openstockapi.providers.dnse import DNSEProvider
+from openstockapi.providers.vndirect import VNDIRECTProvider
+from openstockapi.providers.vci import VCIProvider
+from openstockapi.providers.mbk import MBKProvider
+from openstockapi.providers.fmarket import FmarketProvider
+from openstockapi.providers.kbs import KBSProvider
+
+# In Phase 1, we also instantiate the VCI provider as stub or simple registry
+PROVIDERS = {
+    "mas": MASProvider(),
+    "dnse": DNSEProvider(),
+    "vndirect": VNDIRECTProvider(),
+    "vci": VCIProvider(),
+    "mbk": MBKProvider(),
+    "fmarket": FmarketProvider(),
+    "kbs": KBSProvider(),
+}
+
+def get_provider(name: str):
+    return PROVIDERS.get(name.lower())

openstockapi/providers/dnse.py

@@ -0,0 +1,104 @@
+from datetime import datetime
+from typing import List
+from openstockapi.core.base_provider import BaseProvider
+from openstockapi.core.types import DataTier
+from openstockapi.core.models import OHLCVBar, FinancialItem, OrderBook, OrderBookEntry
+from openstockapi.core.http_client import http_client
+from openstockapi.core.exceptions import DataParseError
+from openstockapi.core.utils import parse_date
+
+class DNSEProvider(BaseProvider):
+    name = "dnse"
+    required_tier = DataTier.FREE
+
+    def get_ohlcv(self, symbol: str, resolution: str, from_date: str, to_date: str) -> List[OHLCVBar]:
+        try:
+            from_dt = parse_date(from_date)
+            to_dt = parse_date(to_date)
+            from_ts = int(from_dt.timestamp())
+            to_ts = int(to_dt.timestamp())
+        except Exception as e:
+            raise ValueError(f"Invalid date format passed to DNSE get_ohlcv: {e}")
+
+        # Map resolution to DNSE resolution values
+        # e.g., "1D" -> "1D", "1m" -> "1", etc.
+        res_map = {"1d": "1D", "1m": "1", "5m": "5", "15m": "15", "1h": "60", "1w": "1W"}
+        dnse_res = res_map.get(resolution.lower(), resolution)
+
+        url = f"https://services.entrade.com.vn/chart-api/v2/ohlc/history?resolution={dnse_res}&symbol={symbol}&from={from_ts}&to={to_ts}"
+        
+        try:
+            res = http_client.request("GET", url)
+            data = res.json()
+            
+            # Format: lists of t (timestamp), o, h, l, c, v
+            t_list = data.get("t", [])
+            o_list = data.get("o", [])
+            h_list = data.get("h", [])
+            l_list = data.get("l", [])
+            c_list = data.get("c", [])
+            v_list = data.get("v", [])
+
+            results = []
+            for i in range(len(t_list)):
+                results.append(OHLCVBar(
+                    symbol=symbol,
+                    timestamp=datetime.fromtimestamp(t_list[i]),
+                    open=float(o_list[i]),
+                    high=float(h_list[i]),
+                    low=float(l_list[i]),
+                    close=float(c_list[i]),
+                    volume=int(v_list[i]),
+                    provider=self.name
+                ))
+            return results
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse OHLCV history from DNSE: {str(e)}")
+
+    def get_financial_statements(self, symbol: str, stmt_type: str, period: str) -> List[FinancialItem]:
+        raise NotImplementedError("DNSE provider does not support financial statements. Use 'mas' instead.")
+
+    async def async_get_ohlcv(self, symbol: str, resolution: str, from_date: str, to_date: str) -> List[OHLCVBar]:
+        try:
+            from_dt = parse_date(from_date)
+            to_dt = parse_date(to_date)
+            from_ts = int(from_dt.timestamp())
+            to_ts = int(to_dt.timestamp())
+        except Exception as e:
+            raise ValueError(f"Invalid date format passed to DNSE get_ohlcv: {e}")
+
+        res_map = {"1d": "1D", "1m": "1", "5m": "5", "15m": "15", "1h": "60", "1w": "1W"}
+        dnse_res = res_map.get(resolution.lower(), resolution)
+
+        url = f"https://services.entrade.com.vn/chart-api/v2/ohlc/history?resolution={dnse_res}&symbol={symbol}&from={from_ts}&to={to_ts}"
+        
+        try:
+            res = await http_client.async_request("GET", url)
+            data = res.json()
+            
+            t_list = data.get("t", [])
+            o_list = data.get("o", [])
+            h_list = data.get("h", [])
+            l_list = data.get("l", [])
+            c_list = data.get("c", [])
+            v_list = data.get("v", [])
+
+            results = []
+            for i in range(len(t_list)):
+                results.append(OHLCVBar(
+                    symbol=symbol,
+                    timestamp=datetime.fromtimestamp(t_list[i]),
+                    open=float(o_list[i]),
+                    high=float(h_list[i]),
+                    low=float(l_list[i]),
+                    close=float(c_list[i]),
+                    volume=int(v_list[i]),
+                    provider=self.name
+                ))
+            return results
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse OHLCV history from DNSE: {str(e)}")
+
+    def get_order_book(self, symbol: str) -> OrderBook:
+        # Requires paid JWT token (stubbed here, in real implementation we fetch using token from session)
+        raise NotImplementedError("Depth API is a premium feature. Authenticable tokens are handled in Control Plane integration.")

openstockapi/providers/fmarket.py

@@ -0,0 +1,58 @@
+from typing import List
+from openstockapi.core.base_provider import BaseProvider
+from openstockapi.core.types import DataTier
+from openstockapi.core.models_fund import FundDetails, FundHolding
+from openstockapi.core.http_client import http_client
+from openstockapi.core.exceptions import DataParseError
+
+class FmarketProvider(BaseProvider):
+    name = "fmarket"
+    required_tier = DataTier.FREE
+
+    def get_ohlcv(self, symbol: str, resolution: str, from_date: str, to_date: str) -> List[any]:
+        raise NotImplementedError()
+
+    def get_financial_statements(self, symbol: str, stmt_type: str, period: str) -> List[any]:
+        raise NotImplementedError()
+
+    def get_fund_details(self, fund_id: int) -> FundDetails:
+        url = f"https://api.fmarket.vn/res/products/{fund_id}"
+        headers = {
+            "Accept": "application/json, text/plain, */*",
+            "Content-Type": "application/json",
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+        }
+        try:
+            res = http_client.request("GET", url, headers=headers)
+            data = res.json()
+            
+            p_data = data.get("data", {})
+            if not p_data:
+                raise DataParseError(f"No fund details data returned by Fmarket for fund_id: {fund_id}")
+
+            raw_holdings = p_data.get("productTopHoldingList", [])
+            holdings = []
+            for h in raw_holdings:
+                holdings.append(FundHolding(
+                    ticker=h.get("stockCode") or h.get("name", ""),
+                    name=h.get("name"),
+                    net_asset_percent=float(h.get("netAssetPercent", 0)),
+                    asset_value=float(h.get("assetValue")) if h.get("assetValue") is not None else None,
+                    volume=float(h.get("volume")) if h.get("volume") is not None else None
+                ))
+
+            return FundDetails(
+                fund_id=int(p_data.get("id")),
+                name=p_data.get("name", ""),
+                short_name=p_data.get("shortName", ""),
+                code=p_data.get("code", ""),
+                price=float(p_data.get("price", 0)),
+                nav=float(p_data.get("nav", 0)),
+                expected_return=p_data.get("expectedReturn"),
+                management_fee=p_data.get("managementFee"),
+                description=p_data.get("description"),
+                holdings=holdings,
+                provider=self.name
+            )
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse fund details from Fmarket: {e}")

openstockapi/providers/kbs.py

@@ -0,0 +1,69 @@
+from typing import List
+from openstockapi.core.base_provider import BaseProvider
+from openstockapi.core.types import DataTier
+from openstockapi.core.models_news import CompanyNewsEntry, CompanyEventEntry
+from openstockapi.core.http_client import http_client
+from openstockapi.core.exceptions import DataParseError
+from openstockapi.core.utils import parse_date
+
+class KBSProvider(BaseProvider):
+    name = "kbs"
+    required_tier = DataTier.FREE
+
+    def get_ohlcv(self, symbol: str, resolution: str, from_date: str, to_date: str) -> List[any]:
+        raise NotImplementedError()
+
+    def get_financial_statements(self, symbol: str, stmt_type: str, period: str) -> List[any]:
+        raise NotImplementedError()
+
+    def _get_headers(self) -> dict:
+        return {
+            "Accept": "application/json, text/plain, */*",
+            "Accept-Language": "en-US,en;q=0.9,vi-VN;q=0.8,vi;q=0.7",
+            "Connection": "keep-alive",
+            "Content-Type": "application/json",
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36"
+        }
+
+    def get_company_news(self, symbol: str, limit: int = 10) -> List[CompanyNewsEntry]:
+        url = f"https://kbbuddywts.kbsec.com.vn/iis-server/investment/stockinfo/news/{symbol}?l=1&p=1&s={limit}"
+        try:
+            res = http_client.request("GET", url, headers=self._get_headers())
+            data = res.json()
+            
+            results = []
+            for item in data:
+                results.append(CompanyNewsEntry(
+                    symbol=symbol,
+                    news_id=int(item.get("ArticleID", 0)),
+                    title=item.get("Title", ""),
+                    publish_date=parse_date(item.get("PublishTime")),
+                    url=item.get("URL"),
+                    summary=item.get("Head"),
+                    provider=self.name
+                ))
+            return results
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse news from KBS: {e}")
+
+    def get_company_events(self, symbol: str, limit: int = 10) -> List[CompanyEventEntry]:
+        url = f"https://kbbuddywts.kbsec.com.vn/iis-server/investment/stockinfo/event/{symbol}?l=1&p=1&s={limit}"
+        try:
+            res = http_client.request("GET", url, headers=self._get_headers())
+            data = res.json()
+            
+            results = []
+            for item in data:
+                # Structure may contain EventTitle, EventDate etc depending on response. 
+                # KBS event schema varies, but we parse gracefully.
+                results.append(CompanyEventEntry(
+                    symbol=symbol,
+                    event_id=str(item.get("EventID", "")),
+                    title=item.get("EventTitle", item.get("Title", "Event")),
+                    event_date=parse_date(item.get("EventDate")) if item.get("EventDate") else None,
+                    details=item.get("EventContent", item.get("Content")),
+                    provider=self.name
+                ))
+            return results
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse events from KBS: {e}")

openstockapi/providers/mas.py

@@ -0,0 +1,92 @@
+from datetime import datetime
+import json
+import urllib.parse
+from typing import List
+from openstockapi.core.base_provider import BaseProvider
+from openstockapi.core.types import DataTier
+from openstockapi.core.models import FinancialItem, OHLCVBar
+from openstockapi.core.http_client import http_client
+from openstockapi.core.exceptions import DataParseError
+
+class MASProvider(BaseProvider):
+    name = "mas"
+    required_tier = DataTier.FREE
+
+    def get_ohlcv(self, symbol: str, resolution: str, from_date: str, to_date: str) -> List[OHLCVBar]:
+        # MAS does not officially support clean OHLC history in free apis doc, DNSE is preferred.
+        # But we implement a basic placeholder or pass.
+        raise NotImplementedError("MAS provider does not support historical OHLCV. Use 'dnse' instead.")
+
+    def get_financial_statements(self, symbol: str, stmt_type: str, period: str) -> List[FinancialItem]:
+        # Normalizes statement types (CDKT -> CDKT, KQKD -> KQKD, etc.)
+        type_mapping = {
+            "income": "KQKD",
+            "balance": "CDKT",
+            "cashflow": "LCTT",
+            "ratios": "CSTC"
+        }
+        mas_type = type_mapping.get(stmt_type.lower(), "CDKT")
+        term_type = "Q" if period.upper() == "Q" else "Y"
+
+        gql_query = f'query{{vsFinancialReportList(StockCode:"{symbol}",Type:"{mas_type}",TermType:"{term_type}"){{YearPeriod,TermCode,Content{{Values{{Name,Value}}}}}}}}'
+        encoded_query = urllib.parse.quote(gql_query)
+        url = f"https://masboard.masvn.com/api/v2/vs/financialReport?query={encoded_query}"
+
+        try:
+            res = http_client.request("GET", url)
+            data = res.json()
+            
+            # MAS returns a list directly or wraps it
+            report_list = []
+            if isinstance(data, list):
+                report_list = data
+            elif isinstance(data, dict):
+                report_list = data.get("data", {}).get("vsFinancialReportList", [])
+
+            results = []
+            for report in report_list:
+                year_period = report.get("YearPeriod", 0)
+                term_code = report.get("TermCode") # e.g. "Q1", "Year"
+                
+                # Deduce quarter
+                quarter = None
+                if term_code and term_code.startswith("Q"):
+                    try:
+                        quarter = int(term_code[1])
+                    except ValueError:
+                        pass
+                
+                items = {}
+                content = report.get("Content", [])
+                if isinstance(content, list) and len(content) > 0:
+                    values = content[0].get("Values", [])
+                    for val in values:
+                        name = val.get("Name")
+                        value = val.get("Value")
+                        if name:
+                            try:
+                                items[name] = float(value) if value is not None else None
+                            except ValueError:
+                                items[name] = None
+                elif isinstance(content, dict):
+                    values = content.get("Values", [])
+                    for val in values:
+                        name = val.get("Name")
+                        value = val.get("Value")
+                        if name:
+                            try:
+                                items[name] = float(value) if value is not None else None
+                            except ValueError:
+                                items[name] = None
+
+                results.append(FinancialItem(
+                    symbol=symbol,
+                    year=int(year_period),
+                    quarter=quarter,
+                    statement_type=stmt_type,
+                    items=items,
+                    provider=self.name
+                ))
+            return results
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse financial statements from MAS: {str(e)}")

openstockapi/providers/mbk.py

@@ -0,0 +1,49 @@
+from typing import List
+from openstockapi.core.base_provider import BaseProvider
+from openstockapi.core.types import DataTier
+from openstockapi.core.models_macro import MacroIndicatorEntry
+from openstockapi.core.http_client import http_client
+from openstockapi.core.exceptions import DataParseError
+
+class MBKProvider(BaseProvider):
+    name = "mbk"
+    required_tier = DataTier.FREE
+
+    def get_ohlcv(self, symbol: str, resolution: str, from_date: str, to_date: str) -> List[any]:
+        raise NotImplementedError()
+
+    def get_financial_statements(self, symbol: str, stmt_type: str, period: str) -> List[any]:
+        raise NotImplementedError()
+
+    def get_macro_indicators(self) -> List[MacroIndicatorEntry]:
+        url = "https://data.maybanktrade.com.vn/data/reportdatatopbynormtype"
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+            "Accept": "application/json, text/javascript, */*; q=0.01",
+            "X-Requested-With": "XMLHttpRequest",
+            "Referer": "https://data.maybanktrade.com.vn/"
+        }
+        
+        # Fetch Money Supply (M2) & Credit data (type=2, normTypeID=51)
+        payload = "type=2&fromYear=2024&toYear=2026&from=1&to=12&normTypeID=51"
+        
+        try:
+            res = http_client.request("POST", url, headers=headers, content=payload)
+            data = res.json()
+            
+            results = []
+            for item in data:
+                val = item.get("NormValue")
+                results.append(MacroIndicatorEntry(
+                    name=item.get("NormName", "M2"),
+                    year=int(item.get("TermYear", 2026)),
+                    period=item.get("ReportTime", ""),
+                    value=float(val) if val is not None else None,
+                    unit=item.get("UnitCode", "Tỷ VNĐ"),
+                    source=item.get("FromSource"),
+                    provider=self.name
+                ))
+            return results
+        except Exception as e:
+            raise DataParseError(f"Failed to fetch/parse Maybank Macro M2 indicators: {e}")