finatic-server-python 0.1.0__py3-none-any.whl

finatic_server/utils/errors.py

@@ -0,0 +1,62 @@
+"""Custom exception classes for the Finatic Server SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class FinaticError(Exception):
+    """Base exception for all Finatic SDK errors."""
+    
+    def __init__(self, message: str, code: Optional[str] = None):
+        self.message = message
+        self.code = code or "UNKNOWN_ERROR"
+        super().__init__(self.message)
+
+
+class ApiError(FinaticError):
+    """Raised when an API request fails."""
+    
+    def __init__(
+        self, 
+        message: str, 
+        status_code: Optional[int] = None,
+        response_data: Optional[Dict[str, Any]] = None
+    ):
+        self.status_code = status_code
+        self.response_data = response_data or {}
+        super().__init__(message, f"API_ERROR_{status_code}" if status_code else "API_ERROR")
+
+
+class AuthenticationError(FinaticError):
+    """Raised when authentication fails."""
+    pass
+
+class AuthorizationError(FinaticError):
+    """Raised when access is denied due to insufficient permissions."""
+    pass
+
+class ValidationError(FinaticError):
+    """Raised when request validation fails."""
+    pass
+
+
+class RateLimitError(ApiError):
+    """Raised when rate limits are exceeded."""
+    
+    def __init__(self, message: str, retry_after: Optional[int] = None):
+        self.retry_after = retry_after
+        super().__init__(message, 429)
+        self.code = "RATE_LIMIT_ERROR"
+
+
+class NetworkError(FinaticError):
+    """Raised when network connectivity issues occur."""
+    
+    def __init__(self, message: str):
+        super().__init__(message, "NETWORK_ERROR")
+
+
+class TimeoutError(FinaticError):
+    """Raised when requests timeout."""
+    
+    def __init__(self, message: str):
+        super().__init__(message, "TIMEOUT_ERROR") 

finatic_server_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: finatic-server-python
+Version: 0.1.0
+Summary: Python SDK for Finatic Server API
+Author-email: Finatic <support@finatic.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/finatic/finatic-server-python
+Project-URL: Documentation, https://docs.finatic.com/python
+Project-URL: Repository, https://github.com/finatic/finatic-server-python
+Project-URL: Issues, https://github.com/finatic/finatic-server-python/issues
+Keywords: finatic,trading,finance,api,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+
+# Finatic Server Python SDK
+
+A Python SDK for integrating with Finatic's server-side trading and portfolio management APIs.
+
+## Installation
+
+```bash
+pip install finatic-server-python
+```
+
+## Quick Start
+
+```python
+import asyncio
+from finatic_server import FinaticServerClient
+
+async def main():
+    # Initialize with API key
+    client = FinaticServerClient("your-api-key")
+    
+    # Option 1: Portal Authentication
+    await client.start_session()
+    portal_url = await client.get_portal_url()
+    print(f"User should visit: {portal_url}")
+    
+    # After user completes authentication in portal, get user info
+    user_info = await client.get_session_user()
+    print(f"Authenticated user: {user_info['user_id']}")
+    
+    # Option 2: Direct Authentication (if you know the user ID)
+    # client = FinaticServerClient("your-api-key", user_id="user123")
+    # await client.start_session()
+    
+    # Now you can access broker data
+    brokers = await client.get_broker_list()
+    print(f"Available brokers: {len(brokers)}")
+    
+    # Get all orders across all pages
+    all_orders = await client.get_all_broker_orders()
+    print(f"Total orders: {len(all_orders)}")
+
+# Run the example
+asyncio.run(main())
+```
+
+## Authentication Flow
+
+The SDK supports two authentication methods:
+
+### 1. Portal Authentication (User completes auth in browser)
+
+```python
+client = FinaticServerClient("your-api-key")
+
+# Start session
+await client.start_session()
+
+# Get portal URL for user authentication
+portal_url = await client.get_portal_url()
+print(f"User should visit: {portal_url}")
+
+# After user completes authentication in portal
+user_info = await client.get_session_user()
+print(f"User ID: {user_info['user_id']}")
+print(f"Access Token: {user_info['access_token']}")
+
+# Now you can make authenticated requests
+brokers = await client.get_broker_list()
+```
+
+### 2. Direct Authentication (Server-side with known user ID)
+
+```python
+client = FinaticServerClient("your-api-key", user_id="user123")
+
+# Start session (automatically authenticates with user ID)
+await client.start_session()
+
+# Now you can make authenticated requests immediately
+brokers = await client.get_broker_list()
+```
+
+## Core Features
+
+- **API Key Authentication**: Secure server-side authentication
+- **Portal Integration**: Get portal URLs for user authentication
+- **Automatic Token Management**: Handles access/refresh tokens automatically
+- **Pagination Support**: Built-in pagination for large datasets
+- **Type-safe API**: Full Pydantic model support
+- **Async/await Support**: Non-blocking operations
+- **Comprehensive Error Handling**: Detailed error types
+
+## API Reference
+
+### Initialization
+
+```python
+client = FinaticServerClient(
+    api_key="your-api-key",
+    user_id="user123",                    # Optional - for direct authentication
+)
+```
+
+### Authentication Methods
+
+- `start_session()` - Start a new session (authenticates directly if user_id provided)
+- `get_portal_url()` - Get portal URL for user authentication (portal flow only)
+- `get_session_user()` - Get user info and tokens after portal completion (portal flow only)
+
+### Broker Data Methods
+
+#### Basic Methods (with pagination support)
+- `get_broker_list()` - Get list of available brokers
+- `get_broker_connections()` - Get broker connections
+- `get_broker_accounts(page=1, per_page=100, options=None, filters=None)` - Get broker accounts
+- `get_broker_orders(page=1, per_page=100, options=None, filters=None)` - Get broker orders
+- `get_broker_positions(page=1, per_page=100, options=None, filters=None)` - Get broker positions
+
+#### Get All Methods (automatically handles pagination)
+- `get_all_broker_accounts(options=None, filters=None)` - Get all broker accounts across all pages
+- `get_all_broker_orders(options=None, filters=None)` - Get all broker orders across all pages
+- `get_all_broker_positions(options=None, filters=None)` - Get all broker positions across all pages
+
+### Filter Options
+
+```python
+from finatic_server.types.broker import BrokerDataOptions, OrdersFilter, PositionsFilter, AccountsFilter
+
+# Basic filtering
+options = BrokerDataOptions(
+    broker_name="robinhood",
+    account_id="123456",
+    symbol="AAPL"
+)
+
+# Advanced filtering for orders
+order_filters = OrdersFilter(
+    status="filled",
+    side="buy",
+    asset_type="stock",
+    created_after="2024-01-01T00:00:00Z"
+)
+
+# Advanced filtering for positions
+position_filters = PositionsFilter(
+    symbol="AAPL",
+    side="long",
+    asset_type="stock"
+)
+
+# Advanced filtering for accounts
+account_filters = AccountsFilter(
+    account_type="margin",
+    status="active",
+    currency="USD"
+)
+```
+
+## Usage Examples
+
+### Get All Orders with Filtering
+
+```python
+# Get all filled orders for a specific symbol
+all_filled_orders = await client.get_all_broker_orders(
+    filters=OrdersFilter(
+        status="filled",
+        symbol="AAPL"
+    )
+)
+print(f"Found {len(all_filled_orders)} filled AAPL orders")
+```
+
+### Pagination Example
+
+```python
+# Get first page of 10 orders
+first_page = await client.get_broker_orders(page=1, per_page=10)
+print(f"First page: {len(first_page)} orders")
+
+# Get second page
+second_page = await client.get_broker_orders(page=2, per_page=10)
+print(f"Second page: {len(second_page)} orders")
+```
+
+### Get All Data for Analysis
+
+```python
+# Get all accounts, orders, and positions
+all_accounts = await client.get_all_broker_accounts()
+all_orders = await client.get_all_broker_orders()
+all_positions = await client.get_all_broker_positions()
+
+print(f"Total accounts: {len(all_accounts)}")
+print(f"Total orders: {len(all_orders)}")
+print(f"Total positions: {len(all_positions)}")
+```
+
+### Filter by Broker
+
+```python
+# Get all orders from Robinhood
+robinhood_orders = await client.get_all_broker_orders(
+    options=BrokerDataOptions(broker_name="robinhood")
+)
+
+# Get all positions from Tasty Trade
+tasty_positions = await client.get_all_broker_positions(
+    options=BrokerDataOptions(broker_name="tasty_trade")
+)
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+```python
+from finatic_server import AuthenticationError, ApiError, NetworkError
+
+try:
+    orders = await client.get_broker_orders()
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+except NetworkError as e:
+    print(f"Network error: {e}")
+except ApiError as e:
+    print(f"API error: {e}")
+```
+
+## Complete Example
+
+```python
+import asyncio
+from finatic_server import FinaticServerClient
+from finatic_server.types.broker import OrdersFilter, BrokerDataOptions
+
+async def main():
+    # Option 1: Portal Authentication (user completes auth in browser)
+    client = FinaticServerClient("your-api-key")
+    
+    try:
+        # Start session
+        await client.start_session()
+        
+        # Get portal URL
+        portal_url = await client.get_portal_url()
+        print(f"Please visit: {portal_url}")
+        
+        # Wait for user to complete authentication
+        input("Press Enter after completing authentication...")
+        
+        # Get user info
+        user_info = await client.get_session_user()
+        print(f"Authenticated as: {user_info['user_id']}")
+        
+        # Option 2: Direct Authentication (if you know the user ID)
+        # client = FinaticServerClient("your-api-key", user_id="user123")
+        # await client.start_session()
+        # print("Directly authenticated!")
+        
+        # Get broker information
+        brokers = await client.get_broker_list()
+        print(f"Available brokers: {[b.name for b in brokers]}")
+        
+        # Get all filled orders
+        filled_orders = await client.get_all_broker_orders(
+            filters=OrdersFilter(status="filled")
+        )
+        print(f"Total filled orders: {len(filled_orders)}")
+        
+        # Get all positions
+        positions = await client.get_all_broker_positions()
+        print(f"Total positions: {len(positions)}")
+        
+        # Get accounts with cash balance
+        accounts = await client.get_all_broker_accounts()
+        for account in accounts:
+            cash = account.cash_balance or 0.0
+            print(f"{account.account_name}: ${cash:,.2f}")
+            
+    except Exception as e:
+        print(f"Error: {e}")
+    finally:
+        await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details. 

finatic_server_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+finatic_server/__init__.py,sha256=M6DZ75v0qK4xOAVLYPzCfCiyNFiFVPTqCIv2yf6LqX8,2558
+finatic_server/core/__init__.py,sha256=j47dRgumMlE0CDAJw-VgFinGwgrxrYeXq1r65gKD3tg,190
+finatic_server/core/api_client.py,sha256=aCGaQFdqd-SggNPptIrNVSeS6eS14N1GrPw_TurU6G0,34131
+finatic_server/core/client.py,sha256=kR9uT1RtjKloDrgDsDtLTSgoR7QInv_j-IuqnZM6SGM,22202
+finatic_server/types/__init__.py,sha256=9tqj5qIUXWmPvvNxdzZ_1ju2dXb6XiV7u986USH66Ew,2002
+finatic_server/types/auth.py,sha256=toeeWxkx_0jLUxJpaANBrqVo7Rys5aQ9DD-biWijXw4,5975
+finatic_server/types/broker.py,sha256=mOA7JKUQpssnji-plJ011U-9izA-K90RHa7wd_PFq2g,8286
+finatic_server/types/common.py,sha256=rrfpA9g3oMZp32sJ7dhhetVGEV442hXYWrEJ-D9ksIc,7472
+finatic_server/types/orders.py,sha256=TW0j6g7eS3cex3SEs1fu8MF9QFViirxMF6S1C3VgQmo,3345
+finatic_server/types/portfolio.py,sha256=_EtUwQy6GmvU9UAMD59d4KePHJkxbQYA0xX5de2D4L8,3031
+finatic_server/utils/__init__.py,sha256=qL0pv3fto3Jy2h8FY3iRg1IMVm9D1-1Oy3w7aNHh_bI,327
+finatic_server/utils/errors.py,sha256=Z_-UVDnorwHfAiZ819BSxki2xVHn6AnOi9_9hpDwW48,1802
+finatic_server_python-0.1.0.dist-info/METADATA,sha256=1q6MBj9arHc9tLGiRAuNTvrv5_T5M9Av8NFGucLPN14,10361
+finatic_server_python-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+finatic_server_python-0.1.0.dist-info/top_level.txt,sha256=5eAfjxxwueQwIup4GCHEyKWX8PNvqhx1BV7C7TA4z50,15
+finatic_server_python-0.1.0.dist-info/RECORD,,

finatic_server_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

finatic_server_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+finatic_server