schwab_rb 0.2.0 → 0.3.0

data/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Setup and Installation
+- `bin/setup` - Install dependencies and set up the development environment
+- `bundle install` - Install gem dependencies
+- `bin/console` - Start an interactive Ruby console with the gem loaded
+
+### Testing
+- `bundle exec rake spec` - Run all RSpec tests
+- `bundle exec rspec` - Run RSpec tests directly
+- `bundle exec rspec spec/path/to/specific_spec.rb` - Run a specific test file
+- `bundle exec rspec spec/path/to/specific_spec.rb:line_number` - Run a specific test
+
+### Linting and Code Quality
+- `bundle exec rubocop` - Run RuboCop linter
+- `bundle exec rubocop -a` - Auto-correct RuboCop violations where possible
+- `bundle exec rake` - Run both tests and linting (default task)
+
+### Gem Management
+- `bundle exec rake build` - Build the gem
+- `bundle exec rake install` - Install the gem locally
+- `bundle exec rake release` - Release a new version (creates git tag and pushes to RubyGems)
+
+## Architecture Overview
+
+### Core Structure
+This is a Ruby gem (`schwab_rb`) that provides a client library for the Charles Schwab API. The architecture follows a modular design:
+
+**Authentication Layer** (`lib/schwab_rb/auth/`):
+- `init_client_easy.rb` - Recommended initialization method that handles token management automatically
+- `init_client_login.rb` - Interactive browser-based authentication flow
+- `init_client_token_file.rb` - Initialize from existing token file
+- `token_manager.rb` - Handles token refresh and persistence
+- `login_flow_server.rb` - Temporary server for OAuth callback handling
+
+**Client Layer** (`lib/schwab_rb/clients/`):
+- `client.rb` - Synchronous HTTP client for API calls
+- `async_client.rb` - Asynchronous client using the `async` gem
+- `base_client.rb` - Shared client functionality
+
+**Data Objects** (`lib/schwab_rb/data_objects/`):
+- Structured Ruby objects for API responses (Account, Quote, Order, etc.)
+- Replaces raw JSON responses with typed objects for better developer experience
+- All API methods support `return_data_objects: false` to get raw JSON if needed
+
+**Order Management** (`lib/schwab_rb/orders/`):
+- `builder.rb` - Fluent interface for constructing complex orders
+- Various enum classes for order parameters (duration, session, instructions, etc.)
+
+### Key Design Patterns
+
+**Three-Tier Client Initialization**:
+1. `init_client_easy()` - Handles everything automatically (recommended)
+2. `init_client_token_file()` - For existing tokens
+3. `init_client_login()` - For interactive authentication
+
+**Data Object Strategy**:
+- All API methods return structured Ruby objects by default
+- Use `return_data_objects: false` for raw JSON responses
+- Data objects are built from JSON using factory patterns
+
+**Async Support**:
+- Both sync and async clients available
+- Async operations use the `async` gem with promises
+- Set `asyncio: true` during client initialization
+
+### Configuration
+
+Environment variables (loaded via `dotenv`):
+- `SCHWAB_API_KEY` - Your Schwab API key
+- `SCHWAB_APP_SECRET` - Your Schwab application secret  
+- `APP_CALLBACK_URL` - OAuth callback URL
+- `TOKEN_PATH` - Path for token storage
+- `SCHWAB_ACCOUNT_NUMBER` - Your account number
+- `SCHWAB_LOGFILE` - Log file path (optional, defaults to STDOUT)
+- `SCHWAB_LOG_LEVEL` - Log level (DEBUG, INFO, WARN, ERROR, FATAL)
+- `SCHWAB_SILENCE_OUTPUT` - Set to 'true' to disable logging
+
+Programmatic configuration:
+```ruby
+SchwabRb.configure do |config|
+  config.logger = Logger.new(STDOUT)
+  config.log_level = 'INFO'
+  config.silence_output = false
+end
+```
+
+### Testing Infrastructure
+
+**Fixtures and Factories**:
+- JSON fixtures in `spec/fixtures/` for realistic API responses
+- Factory classes in `spec/factories/` for creating test objects
+- Extensive mocking of HTTP responses for unit tests
+
+**Test Organization**:
+- Unit tests mirror the `lib/` structure
+- Separate specs for data objects, clients, auth, and orders
+- Uses `async-rspec` for testing async functionality
+
+### Key Dependencies
+- `oauth2` - OAuth2 authentication
+- `async` + `async-http` - Asynchronous HTTP operations
+- `sinatra` + `puma` - Temporary server for OAuth callbacks
+- `dotenv` - Environment variable management
+- `rspec` + `async-rspec` - Testing framework
+- `rubocop` - Code linting
+
+## Common Patterns
+
+### Client Initialization
+Always use `init_client_easy()` for new development:
+```ruby
+client = SchwabRb::Auth.init_client_easy(
+  ENV['SCHWAB_API_KEY'],
+  ENV['SCHWAB_APP_SECRET'], 
+  ENV['APP_CALLBACK_URL'],
+  ENV['TOKEN_PATH']
+)
+```
+
+### Order Building
+Use the fluent builder pattern for complex orders:
+```ruby
+order = SchwabRb::Orders::Builder.new
+  .set_session(:normal)
+  .set_duration(:day)
+  .set_order_type(:market)
+  .add_equity_leg(:buy, 'AAPL', 100)
+  .build
+```
+
+### Error Handling
+Token expiration is handled automatically by `init_client_easy()`. Custom error classes are defined in `lib/schwab_rb/orders/errors.rb`.

data/README.md

@@ -1,4 +1,4 @@
-****# schwab_rb: Schwab API Ruby Client
+# schwab_rb: Schwab API Ruby Client
 
 The `schwab_rb` gem is a Ruby client for interacting with the Schwab API. It provides a simple and flexible interface for accessing Schwab account data, placing orders, retrieving quotes, and more.
 
@@ -204,7 +204,7 @@ response = client.place_order('account_hash', order)
 The gem supports multiple authentication approaches:
 
 1. **Easy Initialization** (Recommended): Automatically handles token storage and refresh
-2. **Token File**: Initialize from a saved token file  
+2. **Token File**: Initialize from a saved token file
 3. **Login Flow**: Interactive browser-based authentication
 
 ### Easy Authentication Setup
@@ -212,7 +212,7 @@ The gem supports multiple authentication approaches:
 ```ruby
 client = SchwabRb::Auth.init_client_easy(
   ENV['SCHWAB_API_KEY'],
-  ENV['SCHWAB_APP_SECRET'], 
+  ENV['SCHWAB_APP_SECRET'],
   ENV['APP_CALLBACK_URL'],
   ENV['TOKEN_PATH']
 )

data/examples/fetch_account_numbers.rb

@@ -4,19 +4,19 @@
 # Script to fetch account numbers data and save as fixture
 # Usage: ruby examples/fetch_account_numbers.rb
 
-require_relative '../lib/schwab_rb'
-require 'dotenv'
-require 'json'
-require 'fileutils'
+require_relative "../lib/schwab_rb"
+require "dotenv"
+require "json"
+require "fileutils"
 
 Dotenv.load
 
 def create_client
-  token_path = ENV['TOKEN_PATH'] || 'schwab_token.json'
+  token_path = ENV["TOKEN_PATH"] || "schwab_token.json"
   SchwabRb::Auth.init_client_easy(
-    ENV['SCHWAB_API_KEY'],
-    ENV['SCHWAB_APP_SECRET'],
-    ENV['APP_CALLBACK_URL'],
+    ENV.fetch("SCHWAB_API_KEY", nil),
+    ENV.fetch("SCHWAB_APP_SECRET", nil),
+    ENV.fetch("APP_CALLBACK_URL", nil),
     token_path
   )
 end
@@ -29,21 +29,18 @@ def fetch_account_numbers
   parsed_data = JSON.parse(response.body, symbolize_names: true)
 
   # Create fixtures directory if it doesn't exist
-  fixtures_dir = File.join(__dir__, '..', 'spec', 'fixtures')
+  fixtures_dir = File.join(__dir__, "..", "spec", "fixtures")
   FileUtils.mkdir_p(fixtures_dir)
 
   # Save the raw response
-  fixture_file = File.join(fixtures_dir, 'account_numbers.json')
+  fixture_file = File.join(fixtures_dir, "account_numbers.json")
   File.write(fixture_file, JSON.pretty_generate(parsed_data))
 
   puts "Account numbers data saved to: #{fixture_file}"
   puts "Sample data: #{parsed_data.first(2)}"
-
-rescue => e
+rescue StandardError => e
   puts "Error fetching account numbers: #{e.message}"
   puts e.backtrace.first(3)
 end
 
-if __FILE__ == $0
-  fetch_account_numbers
-end
+fetch_account_numbers if __FILE__ == $0

data/examples/fetch_user_preferences.rb

@@ -4,19 +4,19 @@
 # Script to fetch user preferences data and save as fixture
 # Usage: ruby examples/fetch_user_preferences.rb
 
-require_relative '../lib/schwab_rb'
-require 'dotenv'
-require 'json'
-require 'fileutils'
+require_relative "../lib/schwab_rb"
+require "dotenv"
+require "json"
+require "fileutils"
 
 Dotenv.load
 
 def create_client
-  token_path = ENV['TOKEN_PATH'] || 'schwab_token.json'
+  token_path = ENV["TOKEN_PATH"] || "schwab_token.json"
   SchwabRb::Auth.init_client_easy(
-    ENV['SCHWAB_API_KEY'],
-    ENV['SCHWAB_APP_SECRET'], 
-    ENV['APP_CALLBACK_URL'],
+    ENV.fetch("SCHWAB_API_KEY", nil),
+    ENV.fetch("SCHWAB_APP_SECRET", nil),
+    ENV.fetch("APP_CALLBACK_URL", nil),
     token_path
   )
 end
@@ -24,26 +24,23 @@ end
 def fetch_user_preferences
   client = create_client
   puts "Fetching user preferences..."
-  
+
   response = client.get_user_preferences
   parsed_data = JSON.parse(response.body, symbolize_names: true)
-  
+
   # Create fixtures directory if it doesn't exist
-  fixtures_dir = File.join(__dir__, '..', 'spec', 'fixtures')
+  fixtures_dir = File.join(__dir__, "..", "spec", "fixtures")
   FileUtils.mkdir_p(fixtures_dir)
-  
+
   # Save the raw response
-  fixture_file = File.join(fixtures_dir, 'user_preferences.json')
+  fixture_file = File.join(fixtures_dir, "user_preferences.json")
   File.write(fixture_file, JSON.pretty_generate(parsed_data))
-  
+
   puts "User preferences data saved to: #{fixture_file}"
   puts "Sample data keys: #{parsed_data.keys.first(5)}"
-  
-rescue => e
+rescue StandardError => e
   puts "Error fetching user preferences: #{e.message}"
   puts e.backtrace.first(3)
 end
 
-if __FILE__ == $0
-  fetch_user_preferences
-end
+fetch_user_preferences if __FILE__ == $0

data/lib/schwab_rb/account.rb

@@ -3,7 +3,7 @@
 module SchwabRb
   class Account
     module Statuses
-      POSITIONS = 'positions'
+      POSITIONS = "positions"
     end
   end
 end

data/lib/schwab_rb/auth/auth_context.rb

@@ -1,4 +1,4 @@
-require 'oauth2'
+require "oauth2"
 
 module SchwabRb::Auth
   class AuthContext

data/lib/schwab_rb/auth/init_client_easy.rb

@@ -1,6 +1,6 @@
-require 'oauth2'
-require_relative 'init_client_token_file'
-require_relative 'init_client_login'
+require "oauth2"
+require_relative "init_client_token_file"
+require_relative "init_client_login"
 
 module SchwabRb::Auth
   def self.init_client_easy(
@@ -12,34 +12,32 @@ module SchwabRb::Auth
     enforce_enums: false,
     callback_timeout: 300.0,
     interactive: true,
-    requested_browser: nil)
+    requested_browser: nil
+  )
 
-    begin
-      if File.exist?(token_path)
-        client = SchwabRb::Auth::init_client_token_file(
-          api_key,
-          app_secret,
-          token_path,
-          enforce_enums: enforce_enums
-        )
-        client.refresh! if client.session.expired?
-        raise OAuth2::Error.new("Token expired") if client.session.expired?
-        client
-      else
-        raise OAuth2::Error.new("No token found")
-      end
-    rescue
-      SchwabRb::Auth::init_client_login(
-        api_key,
-        app_secret,
-        callback_url,
-        token_path,
-        asyncio: asyncio,
-        enforce_enums: enforce_enums,
-        callback_timeout: callback_timeout,
-        interactive: interactive,
-        requested_browser: requested_browser
-      )
-    end
+    raise OAuth2::Error.new("No token found") unless File.exist?(token_path)
+
+    client = SchwabRb::Auth.init_client_token_file(
+      api_key,
+      app_secret,
+      token_path,
+      enforce_enums: enforce_enums
+    )
+    client.refresh! if client.session.expired?
+    raise OAuth2::Error.new("Token expired") if client.session.expired?
+
+    client
+  rescue StandardError
+    SchwabRb::Auth.init_client_login(
+      api_key,
+      app_secret,
+      callback_url,
+      token_path,
+      asyncio: asyncio,
+      enforce_enums: enforce_enums,
+      callback_timeout: callback_timeout,
+      interactive: interactive,
+      requested_browser: requested_browser
+    )
   end
 end

data/lib/schwab_rb/auth/init_client_login.rb

@@ -1,17 +1,19 @@
-require 'openssl'
-require 'uri'
-require 'net/http'
-require 'json'
-require 'oauth2'
+require "openssl"
+require "uri"
+require "net/http"
+require "json"
+require "oauth2"
 # require 'logger'
 
 module SchwabRb::Auth
   class RedirectTimeoutError < StandardError
-    def initialize(msg="Timed out waiting for a callback")
-      super(msg)
+    def initialize(msg = "Timed out waiting for a callback")
+      super
     end
   end
+
   class RedirectServerExitedError < StandardError; end
+
   # class TokenExchangeError < StandardError
   #   def initialize(msg)
   #     super(msg)
@@ -33,15 +35,16 @@ module SchwabRb::Auth
     enforce_enums: false,
     callback_timeout: 300.0,
     interactive: true,
-    requested_browser: nil)
+    requested_browser: nil
+  )
 
-    callback_timeout = if not callback_timeout
-      callback_timeout = 0
+    callback_timeout = if !callback_timeout
+                         0
     elsif callback_timeout < 0
       raise ArgumentError, "callback_timeout must be non-negative"
     else
       callback_timeout
-    end
+                       end
 
     parsed = URI.parse(callback_url)
     raise InvalidHostname.new(parsed.host) unless parsed.host == "127.0.0.1"
@@ -49,9 +52,9 @@ module SchwabRb::Auth
     callback_port = parsed.port || 4567
     callback_path = parsed.path.empty? ? "/" : parsed.path
 
-    cert_file, key_file = self.create_ssl_certificate
+    cert_file, key_file = create_ssl_certificate
 
-    server_thread = SchwabRb::Auth::LoginFlowServer.run_in_thread(
+    SchwabRb::Auth::LoginFlowServer.run_in_thread(
       callback_port: callback_port,
       callback_path: callback_path,
       cert_file: cert_file,
@@ -80,13 +83,13 @@ module SchwabRb::Auth
         raise RedirectServerExitedError if Time.now - start_time > 5
       end
 
-      auth_context = self.build_auth_context(api_key, callback_url)
+      auth_context = build_auth_context(api_key, callback_url)
 
       puts <<~MESSAGE
-      ***********************************************************************
-      Open this URL in your browser to log in:
-      #{auth_context.authorization_url}
-      ***********************************************************************
+        ***********************************************************************
+        Open this URL in your browser to log in:
+        #{auth_context.authorization_url}
+        ***********************************************************************
       MESSAGE
 
       if interactive
@@ -109,7 +112,7 @@ module SchwabRb::Auth
 
       raise RedirectTimeoutError.new unless received_url
 
-      self.client_from_received_url(
+      client_from_received_url(
         api_key,
         app_secret,
         auth_context,
@@ -132,7 +135,7 @@ module SchwabRb::Auth
     cert.not_after = Time.now + (60 * 60 * 24) # 1 day
     cert.serial = 0x0
     cert.version = 2
-    cert.sign(key, OpenSSL::Digest::SHA256.new)
+    cert.sign(key, OpenSSL::Digest.new("SHA256"))
 
     cert_file = Tempfile.new("cert.pem")
     cert_file.write(cert.to_pem)
@@ -142,7 +145,7 @@ module SchwabRb::Auth
     key_file.write(key.to_pem)
     key_file.close
 
-    return cert_file, key_file
+    [cert_file, key_file]
   end
 
   def self.build_auth_context(api_key, callback_url, state: nil)

data/lib/schwab_rb/auth/login_flow_server.rb

@@ -10,7 +10,7 @@ module SchwabRb::Auth
 
     self.queue = Queue.new
 
-    self.disable :logging
+    disable :logging
 
     get "/status" do
       "running"
@@ -34,7 +34,7 @@ module SchwabRb::Auth
         ctx = Puma::MiniSSL::Context.new.tap do |ctx|
           ctx.key = key_file.path
           ctx.cert = cert_file.path
-          ctx.verify_mode=Puma::MiniSSL::VERIFY_NONE
+          ctx.verify_mode = Puma::MiniSSL::VERIFY_NONE
         end
 
         puts ctx.inspect

data/lib/schwab_rb/auth/token.rb

@@ -19,6 +19,6 @@ module SchwabRb::Auth
     end
 
     attr_reader :token, :expires_in, :token_type, :scope,
-      :refresh_token, :id_token, :expires_at
+                :refresh_token, :id_token, :expires_at
   end
 end

data/lib/schwab_rb/auth/token_manager.rb

@@ -1,5 +1,5 @@
-require 'oauth2'
-require 'json'
+require "oauth2"
+require "json"
 
 module SchwabRb::Auth
   class TokenManager
@@ -74,9 +74,7 @@ module SchwabRb::Auth
     end
 
     def to_file
-      File.open(token_path, "w") do |f|
-        f.write(to_json)
-      end
+      File.write(token_path, to_json)
     end
 
     def token_age
@@ -84,7 +82,7 @@ module SchwabRb::Auth
     end
 
     def to_h
-      token_data = {
+      {
         timestamp: timestamp,
         token: {
           expires_in: token.expires_in,
@@ -98,7 +96,7 @@ module SchwabRb::Auth
       }
     end
 
-    def to_json
+    def to_json(*_args)
       to_h.to_json
     end
   end

data/lib/schwab_rb/clients/async_client.rb

@@ -1,11 +1,11 @@
-require 'async'
-require 'async/http'
-require 'json'
-require 'uri'
-require_relative 'base_client'
-require_relative '../utils/logger'
-require_relative '../utils/redactor'
-require_relative '../constants'
+require "async"
+require "async/http"
+require "json"
+require "uri"
+require_relative "base_client"
+require_relative "../utils/logger"
+require_relative "../utils/redactor"
+require_relative "../constants"
 
 module SchwabRb
   class AsyncClient < BaseClient
@@ -28,7 +28,7 @@ module SchwabRb
         dest.query = URI.encode_www_form(params) if params.any?
 
         req_num = req_num()
-        log_request('GET', req_num, dest, params)
+        log_request("GET", req_num, dest, params)
 
         # Use path only since @endpoint already has the base URL
         query_string = params.any? ? "?#{URI.encode_www_form(params)}" : ""
@@ -45,7 +45,7 @@ module SchwabRb
         dest = URI(URI::DEFAULT_PARSER.escape("#{SchwabRb::Constants::SCHWAB_BASE_URL}#{path}"))
 
         req_num = req_num()
-        log_request('POST', req_num, dest, data)
+        log_request("POST", req_num, dest, data)
 
         response = @client.post(path, build_headers, JSON.dump(data))
 
@@ -60,7 +60,7 @@ module SchwabRb
         dest = URI(URI::DEFAULT_PARSER.escape("#{SchwabRb::Constants::SCHWAB_BASE_URL}#{path}"))
 
         req_num = req_num()
-        log_request('PUT', req_num, dest, data)
+        log_request("PUT", req_num, dest, data)
 
         response = @client.put(path, build_headers, JSON.dump(data))
 
@@ -75,7 +75,7 @@ module SchwabRb
         dest = URI(URI::DEFAULT_PARSER.escape("#{SchwabRb::Constants::SCHWAB_BASE_URL}#{path}"))
 
         req_num = req_num()
-        log_request('DELETE', req_num, dest)
+        log_request("DELETE", req_num, dest)
 
         response = @client.delete(path, build_headers)
 
@@ -86,32 +86,30 @@ module SchwabRb
 
     def build_headers
       headers = { "Content-Type" => "application/json" }
-      
+
       # Add authorization header if token is available
-      if @token_manager&.access_token
-        headers["Authorization"] = "Bearer #{@token_manager.access_token}"
-      end
-      
+      headers["Authorization"] = "Bearer #{@token_manager.access_token}" if @token_manager&.access_token
+
       headers
     end
 
     def log_request(method, req_num, dest, data = nil)
       redacted_dest = SchwabRb::Redactor.redact_url(dest.to_s)
       SchwabRb::Logger.logger.info("Req #{req_num}: #{method} to #{redacted_dest}")
-      
-      if data
-        redacted_data = SchwabRb::Redactor.redact_data(data)
-        SchwabRb::Logger.logger.debug("Payload: #{JSON.pretty_generate(redacted_data)}")
-      end
+
+      return unless data
+
+      redacted_data = SchwabRb::Redactor.redact_data(data)
+      SchwabRb::Logger.logger.debug("Payload: #{JSON.pretty_generate(redacted_data)}")
     end
 
     def log_response(response, req_num)
       SchwabRb::Logger.logger.info("Resp #{req_num}: Status #{response.status}")
-      
-      if SchwabRb::Logger.logger.level == ::Logger::DEBUG
-        redacted_body = SchwabRb::Redactor.redact_response_body(response)
-        SchwabRb::Logger.logger.debug("Response body: #{JSON.pretty_generate(redacted_body)}") if redacted_body
-      end
+
+      return unless SchwabRb::Logger.logger.level == ::Logger::DEBUG
+
+      redacted_body = SchwabRb::Redactor.redact_response_body(response)
+      SchwabRb::Logger.logger.debug("Response body: #{JSON.pretty_generate(redacted_body)}") if redacted_body
     end
 
     def req_num