tastytrade 0.2.0

data/docs/python_sdk_analysis.md

@@ -0,0 +1,181 @@
+# Python Tastytrade SDK Analysis
+
+## Overview
+
+This document analyzes the Python Tastytrade SDK's Session implementation to extract patterns and best practices for our Ruby implementation.
+
+## Key Components
+
+### 1. Session Class Structure
+
+The Python SDK's `Session` class is a standalone class (no inheritance) that:
+- Manages authentication state
+- Provides both sync and async methods
+- Implements context manager protocol (`__enter__`/`__exit__`)
+- Handles both production and test environments
+
+```python
+class Session:
+    def __init__(self, username=None, password=None, remember_me=False, 
+                 remember_token=None, two_factor_code=None, dxfeed_tos_compliant=True, 
+                 proxy=None, is_test=False):
+        # Initialize with credentials or remember token
+        # Supports 2FA and proxy configuration
+```
+
+### 2. Authentication Flow
+
+**Login Process:**
+1. POST to `/sessions` endpoint with credentials
+2. Receive session token and user data
+3. Store session token for subsequent requests
+4. Optionally store remember token for future sessions
+
+**Key Features:**
+- Username/password authentication
+- Remember token support for persistent sessions
+- Two-factor authentication support
+- Session expiration tracking
+
+### 3. State Management
+
+The session maintains:
+- `session_token`: Primary authentication credential
+- `remember_token`: For persistent login
+- `user`: User information object
+- `session_expiration`: Token validity timestamp
+- `is_test`: Environment flag (production vs certification)
+
+### 4. HTTP Client Pattern
+
+**Client Library:** Uses `httpx` for HTTP requests
+
+**Request Methods:**
+```python
+def _get(self, path, params=None):
+    url = f'{self.base_url}{path}'
+    return self._session.get(url, params=params, headers=self._headers())
+
+def _post(self, path, data=None, json=None):
+    url = f'{self.base_url}{path}'
+    return self._session.post(url, data=data, json=json, headers=self._headers())
+```
+
+**Key Patterns:**
+- Centralized request methods (`_get`, `_post`, `_put`, `_delete`)
+- Automatic header injection
+- Base URL management based on environment
+- 30-second timeout for all requests
+
+### 5. Error Handling
+
+**Validation Pattern:**
+```python
+def validate_response(response: httpx.Response) -> None:
+    if response.status_code // 100 != 2:
+        try:
+            content = response.json()
+            error = content.get('error', {})
+            raise TastytradeError(
+                error.get('message', 'Unknown error'),
+                error.get('code'),
+                error.get('errors')
+            )
+        except JSONDecodeError:
+            response.raise_for_status()
+```
+
+**Key Features:**
+- Custom `TastytradeError` exception
+- Detailed error parsing from API responses
+- Graceful handling of malformed responses
+- HTTP status code validation
+
+### 6. Response Parsing
+
+**Standard Pattern:**
+```python
+def validate_and_parse(response: httpx.Response) -> dict:
+    validate_response(response)
+    content = response.json()
+    data = content.get('data', {})
+    if not data:
+        raise TastytradeError('No data in response')
+    return dict(data)
+```
+
+**Characteristics:**
+- Validates response before parsing
+- Extracts 'data' field from JSON response
+- Type casting to dictionary
+- Handles missing data gracefully
+
+## Patterns to Adopt for Ruby Implementation
+
+### 1. Session Architecture
+- Single Session class managing all authentication state
+- Support for multiple authentication methods (password, remember token)
+- Environment switching (production/test)
+- Context manager pattern (Ruby: implement with blocks)
+
+### 2. HTTP Client Management
+- Use a robust HTTP client (e.g., Faraday in Ruby)
+- Centralized request methods with automatic header injection
+- Configurable timeouts
+- Proxy support
+
+### 3. Error Handling Strategy
+- Custom exception hierarchy (TastytradeError base class)
+- Parse API error responses for detailed error information
+- Graceful degradation for malformed responses
+- Consistent error reporting
+
+### 4. Authentication State
+- Store session token as instance variable
+- Support remember tokens for persistent sessions
+- Track session expiration
+- Automatic token refresh (if supported by API)
+
+### 5. Configuration Options
+- Environment selection (production/test)
+- Proxy configuration
+- Timeout settings
+- Optional 2FA support
+
+### 6. API Request Pattern
+```ruby
+# Ruby equivalent pattern
+def get(path, params = nil)
+  response = http_client.get(build_url(path), params: params, headers: headers)
+  validate_and_parse(response)
+end
+
+private
+
+def validate_and_parse(response)
+  validate_response(response)
+  data = JSON.parse(response.body)['data']
+  raise TastytradeError, 'No data in response' unless data
+  data
+end
+```
+
+## Implementation Recommendations
+
+1. **Use Faraday** for HTTP client with middleware support
+2. **Implement retry logic** using Faraday middleware
+3. **Add logging** for debugging API interactions
+4. **Support both sync and async** operations (using Async gem)
+5. **Type safety** with Sorbet or RBS type signatures
+6. **Configuration** via environment variables or config object
+7. **Testing** with VCR for recording/replaying HTTP interactions
+
+## Next Steps
+
+1. Create base `Tastytrade::Session` class
+2. Implement authentication methods
+3. Add HTTP client configuration
+4. Create error handling hierarchy
+5. Add response validation and parsing
+6. Implement specific API endpoints
+7. Add comprehensive test coverage

data/exe/tastytrade

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "tastytrade"
+require "tastytrade/cli"
+
+Tastytrade::CLI.start(ARGV)