fintables 0.1.0__py3-none-any.whl

fintables/__init__.py

@@ -0,0 +1,8 @@
+"""Fintables Python Client & CLI."""
+
+from fintables.api.client import FintablesClient
+
+__version__ = "0.1.0"
+
+__all__ = ["FintablesClient", "__version__"]
+

fintables/api/__init__.py

@@ -0,0 +1,3 @@
+from fintables.api.client import FintablesClient
+
+__all__ = ["FintablesClient"]

fintables/api/auth.py

@@ -0,0 +1,87 @@
+from typing import Any
+from fintables.exceptions import AuthError
+
+
+async def login(
+    client: Any,
+    email: str,
+    password: str,
+    base_url: str = "https://api.fintables.com",
+    headers: dict[str, str] | None = None,
+) -> tuple[str, str]:
+    """Logs in using email/password and returns (access_token, refresh_token)."""
+    req_headers = {
+        "User-Agent": "fintables-mobile/323 (2.28.2)",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    if headers:
+        req_headers.update(headers)
+
+    payload = {"email": email, "password": password}
+    try:
+        resp = await client.post(
+            f"{base_url}/auth/token/",
+            json=payload,
+            headers=req_headers,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            access = data.get("access") or data.get("access_token")
+            refresh = data.get("refresh") or data.get("refresh_token", "")
+            if access:
+                return access, refresh
+        elif resp.status_code == 400 and "username" in getattr(resp, "text", ""):
+            resp2 = await client.post(
+                f"{base_url}/auth/token/",
+                json={"username": email, "password": password},
+                headers=req_headers,
+            )
+            if resp2.status_code == 200:
+                data = resp2.json()
+                access = data.get("access") or data.get("access_token")
+                refresh = data.get("refresh") or data.get("refresh_token", "")
+                if access:
+                    return access, refresh
+    except Exception as e:
+        if isinstance(e, AuthError):
+            raise
+        raise AuthError(f"Giriş isteği sırasında hata oluştu: {type(e).__name__}") from e
+
+    error_msg = resp.text if "resp" in locals() and hasattr(resp, "text") else "Bilinmeyen hata"
+    raise AuthError(
+        f"Giriş yapılamadı: {error_msg}. "
+        "Lütfen FINTABLES_USERNAME/FINTABLES_EMAIL ve FINTABLES_PASSWORD ayarlarınızı kontrol edin."
+    )
+
+
+async def refresh_token(
+    client: Any,
+    refresh: str,
+    base_url: str = "https://api.fintables.com",
+    headers: dict[str, str] | None = None,
+) -> str:
+    """Refreshes access_token using refresh_token."""
+    req_headers = {
+        "User-Agent": "fintables-mobile/323 (2.28.2)",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    if headers:
+        req_headers.update(headers)
+
+    try:
+        resp = await client.post(
+            f"{base_url}/auth/token/refresh/",
+            json={"refresh": refresh},
+            headers=req_headers,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            access = data.get("access") or data.get("access_token")
+            if access:
+                return access
+    except Exception as e:
+        raise AuthError(f"Token yenileme sırasında hata oluştu: {type(e).__name__}") from e
+
+    raise AuthError("Token yenilenemedi. Lütfen tekrar giriş yapın.")

fintables/api/client.py

@@ -0,0 +1,184 @@
+import inspect
+import logging
+from types import TracebackType
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+try:
+    from curl_cffi.requests import AsyncSession
+except ImportError:
+    AsyncSession = None  # type: ignore
+
+from fintables.api.auth import login, refresh_token
+from fintables.config import Settings, settings
+from fintables.exceptions import APIError, AuthError, NotFoundError
+
+
+_logger = logging.getLogger("fintables.client")
+_ALLOWED_HOSTS = {"api.fintables.com", "gate.fintables.com"}
+
+
+class FintablesClient:
+    """Asynchronous HTTP client for Fintables API."""
+
+    def __init__(
+        self,
+        custom_settings: Settings | None = None,
+        access_token: str | None = None,
+        refresh_token_val: str | None = None,
+        client: Any = None,
+    ):
+        self.settings = custom_settings or settings
+        self._access_token = access_token
+        self._refresh_token = refresh_token_val
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+        else:
+            if AsyncSession is not None:
+                self._client = AsyncSession(impersonate="chrome124", timeout=30.0)
+            else:
+                self._client = httpx.AsyncClient(timeout=30.0)
+            self._owns_client = True
+
+    async def __aenter__(self) -> "FintablesClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owns_client:
+            if hasattr(self._client, "aclose"):
+                await self._client.aclose()
+            elif hasattr(self._client, "close"):
+                res = self._client.close()
+                if inspect.isawaitable(res):
+                    await res
+
+    async def _ensure_auth(self) -> None:
+        """Ensures that client has a valid access token."""
+        if self._access_token:
+            return
+
+        login_id = self.settings.email_or_username
+        if login_id and self.settings.password:
+            access, refresh = await login(
+                self._client,
+                login_id,
+                self.settings.password,
+                base_url=self.settings.base_url,
+                headers=self.settings.default_headers,
+            )
+            self._access_token = access
+            self._refresh_token = refresh
+        else:
+            raise AuthError(
+                "Bu işlem için kimlik doğrulama gereklidir. "
+                "Lütfen .env dosyasında FINTABLES_USERNAME veya FINTABLES_EMAIL ve FINTABLES_PASSWORD değerlerini ayarlayın."
+            )
+
+    async def _try_refresh_or_relogin(self) -> bool:
+        """Attempts to refresh token or re-login. Returns True if succeeded."""
+        if self._refresh_token:
+            try:
+                new_access = await refresh_token(
+                    self._client,
+                    self._refresh_token,
+                    base_url=self.settings.base_url,
+                    headers=self.settings.default_headers,
+                )
+                self._access_token = new_access
+                return True
+            except Exception as e:
+                _logger.debug("Token refresh failed: %s", type(e).__name__)
+
+        login_id = self.settings.email_or_username
+        if login_id and self.settings.password:
+            try:
+                access, refresh = await login(
+                    self._client,
+                    login_id,
+                    self.settings.password,
+                    base_url=self.settings.base_url,
+                    headers=self.settings.default_headers,
+                )
+                self._access_token = access
+                self._refresh_token = refresh
+                return True
+            except Exception as e:
+                _logger.debug("Re-login failed: %s", type(e).__name__)
+
+        return False
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        requires_auth: bool = False,
+        is_gate: bool = False,
+        headers: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Sends an HTTP request with automatic headers and authentication handling."""
+        base_url = self.settings.gate_url if is_gate else self.settings.base_url
+        if path.startswith("http"):
+            parsed = urlparse(path)
+            if parsed.hostname not in _ALLOWED_HOSTS:
+                raise ValueError(f"Disallowed host in URL: {parsed.hostname}")
+            url = path
+        else:
+            url = f"{base_url}{path}"
+
+        req_headers = dict(self.settings.gate_headers if is_gate else self.settings.default_headers)
+        if headers:
+            req_headers.update(headers)
+
+        if requires_auth:
+            await self._ensure_auth()
+            req_headers["Authorization"] = f"Bearer {self._access_token}"
+
+        response = await self._client.request(method, url, headers=req_headers, **kwargs)  # type: ignore[arg-type]
+
+        if response.status_code == 401 and requires_auth:
+            # Attempt refresh / re-login once
+            refreshed = await self._try_refresh_or_relogin()
+            if refreshed:
+                req_headers["Authorization"] = f"Bearer {self._access_token}"
+                response = await self._client.request(method, url, headers=req_headers, **kwargs)  # type: ignore[arg-type]
+            else:
+                raise AuthError("Oturum süresi doldu veya kimlik doğrulama başarısız oldu.")
+
+        if response.status_code == 404:
+            raise NotFoundError(f"İstenen kaynak bulunamadı (404): {url}")
+
+        if response.status_code >= 400:
+            resp_text = response.text
+            truncated = (resp_text[:200] + "...") if len(resp_text) > 200 else resp_text
+            raise APIError(
+                f"API hatası ({response.status_code}): {truncated}",
+                status_code=response.status_code,
+                response_text=resp_text,
+            )
+
+        return response
+
+    async def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("POST", path, **kwargs)
+
+    async def put(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("PUT", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("DELETE", path, **kwargs)

fintables/api/endpoints/__init__.py

@@ -0,0 +1,65 @@
+from fintables.api.endpoints.analyst_ratings import get_analyst_ratings
+from fintables.api.endpoints.agenda import get_agenda
+from fintables.api.endpoints.companies import get_company
+from fintables.api.endpoints.newsletter import get_newsletter, list_newsletters
+from fintables.api.endpoints.post import get_post, list_posts
+from fintables.api.endpoints.video import get_video, list_videos
+from fintables.api.endpoints.feed import get_feed, get_topic_feed
+from fintables.api.endpoints.memo import (
+    create_memo,
+    delete_memo,
+    list_memos,
+    update_memo,
+)
+from fintables.api.endpoints.search import search
+from fintables.api.endpoints.sheets import get_sheets
+from fintables.api.endpoints.symbols import get_symbol_summary
+from fintables.api.endpoints.watchlist import add_favorite, remove_favorite
+from fintables.api.endpoints.funds import get_fund, get_fund_info
+from fintables.api.endpoints.portfolio import (
+    add_transaction,
+    create_portfolio,
+    delete_portfolio,
+    get_positions,
+    list_portfolios,
+    update_portfolio,
+)
+from fintables.api.endpoints.notifications import (
+    get_unread_status,
+    list_notifications,
+    mark_notifications_as_read,
+)
+
+__all__ = [
+    "get_company",
+    "get_symbol_summary",
+    "get_analyst_ratings",
+    "get_agenda",
+    "get_newsletter",
+    "list_newsletters",
+    "get_post",
+    "list_posts",
+    "get_video",
+    "list_videos",
+    "search",
+    "get_sheets",
+    "get_feed",
+    "get_topic_feed",
+    "add_favorite",
+    "remove_favorite",
+    "list_memos",
+    "create_memo",
+    "update_memo",
+    "delete_memo",
+    "get_fund",
+    "get_fund_info",
+    "list_portfolios",
+    "create_portfolio",
+    "delete_portfolio",
+    "update_portfolio",
+    "get_positions",
+    "add_transaction",
+    "list_notifications",
+    "get_unread_status",
+    "mark_notifications_as_read",
+]

fintables/api/endpoints/agenda.py

@@ -0,0 +1,23 @@
+from typing import Literal
+
+from fintables.api.client import FintablesClient
+from fintables.models.agenda import AgendaItem
+
+AgendaTime = Literal["today", "thisWeek", "nextWeek"]
+
+
+async def get_agenda(
+    client: FintablesClient,
+    time: AgendaTime = "today",
+) -> list[AgendaItem]:
+    """Ajanda etkinliklerini getirir (bugün / bu hafta / gelecek hafta)."""
+    response = await client.get(
+        "/mobile/agenda/",
+        params={"time": time},
+        requires_auth=True,
+    )
+    data = response.json()
+    if isinstance(data, list):
+        return [AgendaItem.model_validate(item) for item in data]
+    # API ileride sayfalı yanıt dönerse results listesini kullan
+    return [AgendaItem.model_validate(item) for item in data.get("results", [])]

fintables/api/endpoints/analyst_ratings.py

@@ -0,0 +1,26 @@
+from fintables.api.client import FintablesClient
+from fintables.models.analyst_rating import AnalystRatingList
+
+
+async def get_analyst_ratings(
+    client: FintablesClient,
+    ticker: str,
+    brokerage_id: str | None = None,
+    in_model_portfolio: bool | None = None,
+) -> AnalystRatingList:
+    """Fetches analyst ratings for a given symbol."""
+    ticker_clean = ticker.strip().upper()
+    params: dict[str, str] = {
+        "code": ticker_clean,
+        "brokerage_id": brokerage_id or "",
+    }
+    if in_model_portfolio is not None:
+        params["in_model_portfolio"] = "true" if in_model_portfolio else "false"
+    else:
+        params["in_model_portfolio"] = ""
+
+    response = await client.get("/analyst-ratings/", params=params)
+    data = response.json()
+    if isinstance(data, list):
+        return AnalystRatingList(results=data)
+    return AnalystRatingList.model_validate(data)

fintables/api/endpoints/companies.py

@@ -0,0 +1,9 @@
+from fintables.api.client import FintablesClient
+from fintables.models.company import Company
+
+
+async def get_company(client: FintablesClient, ticker: str) -> Company:
+    """Fetches company profile and ratio types."""
+    ticker_clean = ticker.strip().upper()
+    response = await client.get(f"/companies/{ticker_clean}/")
+    return Company.model_validate(response.json())

fintables/api/endpoints/feed.py

@@ -0,0 +1,47 @@
+from fintables.api.client import FintablesClient
+from fintables.models.feed import FeedPage
+
+
+async def get_feed(
+    client: FintablesClient,
+    ticker: str,
+    page_size: int = 30,
+    cursor: str | None = None,
+) -> FeedPage:
+    """Fetches topic feed (news, posts, newsletter, articles) for a given symbol."""
+    ticker_clean = ticker.strip().upper()
+    params: dict[str, str | int] = {
+        "symbols": ticker_clean,
+        "for_everyone": 0,
+        "page_size": page_size,
+    }
+    if cursor:
+        params["cursor"] = cursor
+
+    response = await client.get(
+        "/topic-feed/",
+        params=params,
+        requires_auth=True,
+    )
+    return FeedPage.model_validate(response.json())
+
+
+async def get_topic_feed(
+    client: FintablesClient,
+    page_size: int = 100,
+    cursor: str | None = None,
+) -> FeedPage:
+    """Fetches global topic feed without a specific symbol."""
+    params: dict[str, str | int] = {
+        "only_pro": 1,
+        "page_size": page_size,
+    }
+    if cursor:
+        params["cursor"] = cursor
+
+    response = await client.get(
+        "/topic-feed/",
+        params=params,
+        requires_auth=True,
+    )
+    return FeedPage.model_validate(response.json())

fintables/api/endpoints/funds.py

@@ -0,0 +1,14 @@
+from fintables.api.client import FintablesClient
+from fintables.models.fund import Fund, FundInfo
+
+async def get_fund(client: FintablesClient, code: str) -> Fund:
+    """Fetches general information about a fund."""
+    code_clean = code.strip().upper()
+    response = await client.get(f"/funds/{code_clean}/")
+    return Fund.model_validate(response.json())
+
+async def get_fund_info(client: FintablesClient, code: str) -> FundInfo:
+    """Fetches detailed information and portfolio of a fund."""
+    code_clean = code.strip().upper()
+    response = await client.get(f"/funds/{code_clean}/info/")
+    return FundInfo.model_validate(response.json())

fintables/api/endpoints/memo.py

@@ -0,0 +1,36 @@
+from fintables.api.client import FintablesClient
+from fintables.models.memo import Memo
+
+
+async def list_memos(client: FintablesClient) -> list[Memo]:
+    """Lists all memos for the authenticated user."""
+    response = await client.get("/memos/", requires_auth=True)
+    data = response.json()
+    return [Memo.model_validate(item) for item in data]
+
+
+async def create_memo(client: FintablesClient, code: str, content: str) -> Memo:
+    """Creates a new memo for a symbol."""
+    code_clean = code.strip().upper()
+    response = await client.post(
+        "/memos/",
+        json={"code": code_clean, "content": content},
+        requires_auth=True,
+    )
+    return Memo.model_validate(response.json())
+
+
+async def update_memo(client: FintablesClient, memo_id: int, code: str, content: str) -> Memo:
+    """Updates an existing memo."""
+    code_clean = code.strip().upper()
+    response = await client.put(
+        f"/memos/{memo_id}/",
+        json={"id": memo_id, "code": code_clean, "content": content},
+        requires_auth=True,
+    )
+    return Memo.model_validate(response.json())
+
+
+async def delete_memo(client: FintablesClient, memo_id: int) -> None:
+    """Deletes a memo by ID."""
+    await client.delete(f"/memos/{memo_id}/", requires_auth=True)

fintables/api/endpoints/newsletter.py

@@ -0,0 +1,36 @@
+from fintables.api.client import FintablesClient
+from fintables.models.newsletter import NewsletterDetail, NewsletterPage
+
+
+async def list_newsletters(
+    client: FintablesClient,
+    main_category: str = "bist",
+    page_size: int = 100,
+    page: int | None = None,
+) -> NewsletterPage:
+    """Bültenleri listeler."""
+    params: dict[str, str | int] = {
+        "main_category": main_category,
+        "page_size": page_size,
+    }
+    if page is not None:
+        params["page"] = page
+
+    response = await client.get(
+        "/newsletters/",
+        params=params,
+        requires_auth=True,
+    )
+    return NewsletterPage.model_validate(response.json())
+
+
+async def get_newsletter(
+    client: FintablesClient,
+    slug: str,
+) -> NewsletterDetail:
+    """Bülten detayını (içeriğiyle birlikte) getirir."""
+    response = await client.get(
+        f"/newsletters/{slug}/",
+        requires_auth=True,
+    )
+    return NewsletterDetail.model_validate(response.json())

fintables/api/endpoints/notifications.py

@@ -0,0 +1,41 @@
+from fintables.api.client import FintablesClient
+from fintables.models.notification import (
+    MarkAsReadResponse,
+    NotificationPage,
+    NotificationUnreadStatus,
+)
+
+
+async def list_notifications(
+    client: FintablesClient,
+    page_size: int = 100,
+) -> NotificationPage:
+    """Fetches user notifications."""
+    params: dict[str, str | int] = {
+        "page_size": page_size,
+    }
+
+    response = await client.get(
+        "/notifications/",
+        params=params,
+        requires_auth=True,
+    )
+    return NotificationPage.model_validate(response.json())
+
+
+async def get_unread_status(client: FintablesClient) -> NotificationUnreadStatus:
+    """Checks whether the user has unread notifications and returns the last read timestamp."""
+    response = await client.get(
+        "/notifications/unread_count/",
+        requires_auth=True,
+    )
+    return NotificationUnreadStatus.model_validate(response.json())
+
+
+async def mark_notifications_as_read(client: FintablesClient) -> MarkAsReadResponse:
+    """Marks all user notifications as read."""
+    response = await client.post(
+        "/notifications/mark_as_read/",
+        requires_auth=True,
+    )
+    return MarkAsReadResponse.model_validate(response.json())

fintables/api/endpoints/portfolio.py

@@ -0,0 +1,95 @@
+from fintables.api.client import FintablesClient
+from fintables.models.portfolio import Portfolio, PortfolioPage, PositionPage, Transaction
+
+
+async def list_portfolios(
+    client: FintablesClient,
+    page_size: int = 100,
+) -> PortfolioPage:
+    """Kullanıcının sanal portföylerini listeler."""
+    response = await client.get(
+        "/portfolios/",
+        params={"page_size": page_size},
+        requires_auth=True,
+    )
+    return PortfolioPage.model_validate(response.json())
+
+
+async def create_portfolio(
+    client: FintablesClient,
+    title: str,
+) -> Portfolio:
+    """Yeni bir sanal portföy oluşturur."""
+    response = await client.post(
+        "/portfolios/",
+        json={"title": title},
+        requires_auth=True,
+    )
+    return Portfolio.model_validate(response.json())
+
+
+async def delete_portfolio(
+    client: FintablesClient,
+    portfolio_id: str,
+) -> None:
+    """Belirtilen sanal portföyü siler."""
+    await client.delete(
+        f"/portfolios/{portfolio_id}/",
+        requires_auth=True,
+    )
+
+
+async def update_portfolio(
+    client: FintablesClient,
+    portfolio_id: str,
+    new_title: str,
+) -> Portfolio:
+    """Portföy adını günceller."""
+    response = await client.request(
+        "PATCH",
+        f"/portfolios/{portfolio_id}/",
+        json={"id": portfolio_id, "title": new_title},
+        requires_auth=True,
+    )
+    return Portfolio.model_validate(response.json())
+
+
+async def get_positions(
+    client: FintablesClient,
+    portfolio_id: str,
+) -> PositionPage:
+    """Portföydeki pozisyonları (varlıkları) getirir."""
+    response = await client.get(
+        f"/portfolios/{portfolio_id}/positions/",
+        requires_auth=True,
+    )
+    data = response.json()
+    # API doğrudan liste de döndürebilir
+    if isinstance(data, list):
+        data = {"results": data}
+    return PositionPage.model_validate(data)
+
+
+async def add_transaction(
+    client: FintablesClient,
+    portfolio_id: str,
+    code: str,
+    side: str,
+    amount: str | int | float,
+    price: str | float,
+    date: str,
+) -> Transaction:
+    """Portföye alış (BUY) veya satış (SELL) işlemi ekler."""
+    payload = {
+        "code": code.strip().upper(),
+        "side": side.upper(),
+        "amount": str(amount),
+        "price": str(price),
+        "date": date,
+    }
+    response = await client.post(
+        f"/portfolios/{portfolio_id}/transactions/",
+        json=payload,
+        requires_auth=True,
+    )
+    return Transaction.model_validate(response.json())