schwab 0.2.0

data/lib/schwab/configuration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Schwab
+  # Configuration storage for Schwab SDK
+  #
+  # @example Configure the SDK
+  #   Schwab.configure do |config|
+  #     config.client_id = "your_client_id"
+  #     config.client_secret = "your_client_secret"
+  #     config.redirect_uri = "http://localhost:3000/callback"
+  #     config.response_format = :hash # or :resource
+  #   end
+  class Configuration
+    # @!attribute client_id
+    #   @return [String] OAuth client ID from Schwab developer portal
+    # @!attribute client_secret
+    #   @return [String] OAuth client secret from Schwab developer portal
+    # @!attribute redirect_uri
+    #   @return [String] OAuth callback URL configured in Schwab developer portal
+    # @!attribute api_base_url
+    #   @return [String] Base URL for Schwab API (default: https://api.schwabapi.com)
+    # @!attribute api_version
+    #   @return [String] API version to use (default: v1)
+    # @!attribute logger
+    #   @return [Logger, nil] Logger instance for debugging
+    # @!attribute timeout
+    #   @return [Integer] Request timeout in seconds (default: 30)
+    # @!attribute open_timeout
+    #   @return [Integer] Connection open timeout in seconds (default: 30)
+    # @!attribute faraday_adapter
+    #   @return [Symbol] Faraday adapter to use (default: Faraday.default_adapter)
+    # @!attribute max_retries
+    #   @return [Integer] Maximum number of retries for failed requests (default: 3)
+    # @!attribute retry_delay
+    #   @return [Integer] Delay in seconds between retries (default: 1)
+    # @!attribute response_format
+    #   @return [Symbol] Response format (:hash or :resource, default: :hash)
+    #     - :hash returns plain Ruby hashes (default, backward compatible)
+    #     - :resource returns Sawyer::Resource-like objects with method access
+    attr_accessor :client_id,
+      :client_secret,
+      :redirect_uri,
+      :api_base_url,
+      :api_version,
+      :logger,
+      :timeout,
+      :open_timeout,
+      :faraday_adapter,
+      :max_retries,
+      :retry_delay
+
+    attr_reader :response_format
+
+    def initialize
+      @api_base_url = "https://api.schwabapi.com"
+      @api_version = "v1"
+      @timeout = 30
+      @open_timeout = 30
+      @faraday_adapter = Faraday.default_adapter
+      @max_retries = 3
+      @retry_delay = 1
+      @logger = nil
+      @response_format = :hash
+    end
+
+    # Set response format with validation
+    #
+    # @param format [Symbol] The response format to use (:hash or :resource)
+    # @raise [ArgumentError] if format is not :hash or :resource
+    # @example Set response format to resource objects
+    #   config.response_format = :resource
+    def response_format=(format)
+      valid_formats = [:hash, :resource]
+      unless valid_formats.include?(format)
+        raise ArgumentError, "Invalid response_format: #{format}. Must be :hash or :resource"
+      end
+
+      @response_format = format
+    end
+
+    # Get the full API endpoint URL with version
+    def api_endpoint
+      "#{api_base_url}/#{api_version}"
+    end
+
+    # OAuth-specific endpoints
+    # @return [String] The OAuth authorization URL
+    def oauth_authorize_url
+      "#{api_base_url}/v1/oauth/authorize"
+    end
+
+    # Get the OAuth token endpoint URL
+    # @return [String] The OAuth token URL
+    def oauth_token_url
+      "#{api_base_url}/v1/oauth/token"
+    end
+
+    # Validate that required OAuth parameters are present
+    def validate!
+      missing = []
+      missing << "client_id" if client_id.nil? || client_id.empty?
+      missing << "client_secret" if client_secret.nil? || client_secret.empty?
+      missing << "redirect_uri" if redirect_uri.nil? || redirect_uri.empty?
+
+      unless missing.empty?
+        raise Error, "Missing required configuration: #{missing.join(", ")}"
+      end
+
+      # Validate response_format
+      valid_formats = [:hash, :resource]
+      unless valid_formats.include?(response_format)
+        raise Error, "Invalid response_format: #{response_format}. Must be :hash or :resource"
+      end
+
+      true
+    end
+
+    # Check if OAuth credentials are configured
+    def oauth_configured?
+      !client_id.nil? && !client_secret.nil? && !redirect_uri.nil?
+    end
+
+    # Convert configuration to a hash
+    def to_h
+      {
+        client_id: client_id,
+        client_secret: client_secret,
+        redirect_uri: redirect_uri,
+        api_base_url: api_base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        faraday_adapter: faraday_adapter,
+        max_retries: max_retries,
+        retry_delay: retry_delay,
+        logger: logger,
+        response_format: response_format,
+      }
+    end
+  end
+end

data/lib/schwab/connection.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/middleware"
+require_relative "middleware/authentication"
+
+module Schwab
+  # HTTP connection builder for Schwab API
+  module Connection
+    class << self
+      # Build a Faraday connection with the configured middleware stack
+      #
+      # @param access_token [String, nil] OAuth access token for authentication
+      # @param config [Configuration] Configuration object with connection settings
+      # @return [Faraday::Connection] Configured Faraday connection
+      def build(access_token: nil, config: nil)
+        config ||= Schwab.configuration || Configuration.new
+
+        Faraday.new(url: config.api_base_url) do |conn|
+          # Request middleware (executed in order)
+          conn.request(:json) # Encode request bodies as JSON
+          conn.request(:authorization, "Bearer", access_token) if access_token
+
+          # Response middleware (executed in reverse order)
+          conn.response(:json, content_type: /\bjson$/) # Parse JSON responses
+          conn.response(:raise_error) # Raise exceptions for 4xx/5xx responses
+          conn.response(:logger, config.logger, { headers: false, bodies: false }) if config.logger
+
+          # Adapter (must be last)
+          conn.adapter(config.faraday_adapter)
+
+          # Connection options
+          conn.options.timeout = config.timeout
+          conn.options.open_timeout = config.open_timeout
+        end
+      end
+
+      # Build a connection with automatic token refresh capability
+      #
+      # @param access_token [String] Initial access token
+      # @param refresh_token [String, nil] Refresh token for automatic refresh
+      # @param on_token_refresh [Proc, nil] Callback when token is refreshed
+      # @param config [Configuration] Configuration object
+      # @return [Faraday::Connection] Configured connection with refresh capability
+      def build_with_refresh(access_token:, refresh_token: nil, on_token_refresh: nil, config: nil)
+        config ||= Schwab.configuration || Configuration.new
+
+        Faraday.new(url: config.api_base_url) do |conn|
+          # Request middleware
+          conn.request(:json)
+
+          # Custom middleware for token refresh will be added here
+          if refresh_token
+            conn.use(
+              Middleware::TokenRefresh,
+              access_token: access_token,
+              refresh_token: refresh_token,
+              client_id: config.client_id,
+              client_secret: config.client_secret,
+              on_token_refresh: on_token_refresh,
+            )
+          else
+            conn.request(:authorization, "Bearer", access_token)
+          end
+
+          # Response middleware
+          conn.response(:json, content_type: /\bjson$/)
+          conn.response(:raise_error)
+          conn.response(:logger, config.logger, { headers: false, bodies: false }) if config.logger
+
+          # Adapter
+          conn.adapter(config.faraday_adapter)
+
+          # Connection options
+          conn.options.timeout = config.timeout
+          conn.options.open_timeout = config.open_timeout
+        end
+      end
+    end
+  end
+end

data/lib/schwab/error.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Schwab
+  # Base error class for all Schwab SDK errors
+  class Error < StandardError; end
+
+  # Base class for all API-related errors
+  class ApiError < Error
+    attr_reader :status, :response_body, :response_headers
+
+    def initialize(message = nil, status: nil, response_body: nil, response_headers: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+      @response_headers = response_headers
+    end
+  end
+
+  # Raised when API returns 401 Unauthorized
+  class AuthenticationError < ApiError; end
+
+  # Raised when the access token has expired
+  class TokenExpiredError < AuthenticationError; end
+
+  # Raised when API returns 403 Forbidden
+  class AuthorizationError < ApiError; end
+
+  # Raised when API returns 404 Not Found
+  class NotFoundError < ApiError; end
+
+  # Raised when API returns 429 Too Many Requests
+  class RateLimitError < ApiError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **options)
+      super(message, **options)
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised when API returns 5xx Server Error
+  class ServerError < ApiError; end
+
+  # Raised when API returns 400 Bad Request
+  class BadRequestError < ApiError
+    attr_accessor :response_body
+  end
+
+  # Raised when API returns an unexpected status code
+  class UnexpectedResponseError < ApiError; end
+end

data/lib/schwab/market_data.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Schwab
+  # Market Data API endpoints for retrieving quotes, price history, and market information
+  module MarketData
+    class << self
+      # Get quotes for one or more symbols
+      #
+      # @param symbols [String, Array<String>] Symbol(s) to get quotes for
+      # @param fields [String, Array<String>, nil] Quote fields to include (e.g., "quote", "fundamental")
+      # @param indicative [Boolean] Whether to include indicative quotes
+      # @param client [Schwab::Client, nil] Optional client instance (uses default if not provided)
+      # @return [Hash] Quote data for the requested symbols
+      # @example Get quotes for multiple symbols
+      #   Schwab::MarketData.get_quotes(["AAPL", "MSFT"])
+      # @example Get quotes with specific fields
+      #   Schwab::MarketData.get_quotes("AAPL", fields: ["quote", "fundamental"])
+      def get_quotes(symbols, fields: nil, indicative: false, client: nil)
+        client ||= default_client
+        params = {
+          symbols: normalize_symbols(symbols),
+          indicative: indicative,
+        }
+        params[:fields] = normalize_fields(fields) if fields
+
+        client.get("/marketdata/v1/quotes", params)
+      end
+
+      # Get detailed quote for a single symbol
+      #
+      # @param symbol [String] The symbol to get a quote for
+      # @param fields [String, Array<String>, nil] Quote fields to include
+      # @param client [Schwab::Client, nil] Optional client instance
+      # @return [Hash] Detailed quote data for the symbol
+      # @example Get a single quote
+      #   Schwab::MarketData.get_quote("AAPL")
+      def get_quote(symbol, fields: nil, client: nil)
+        client ||= default_client
+        path = "/marketdata/v1/#{URI.encode_www_form_component(symbol)}/quotes"
+        params = {}
+        params[:fields] = normalize_fields(fields) if fields
+
+        client.get(path, params)
+      end
+
+      # Get price history for a symbol
+      #
+      # @param symbol [String] The symbol to get price history for
+      # @param period_type [String, nil] The type of period ("day", "month", "year", "ytd")
+      # @param period [Integer, nil] The number of periods
+      # @param frequency_type [String, nil] The type of frequency ("minute", "daily", "weekly", "monthly")
+      # @param frequency [Integer, nil] The frequency value
+      # @param start_date [Time, Date, String, Integer, nil] Start date for history
+      # @param end_date [Time, Date, String, Integer, nil] End date for history
+      # @param need_extended_hours [Boolean] Include extended hours data
+      # @param need_previous_close [Boolean] Include previous close data
+      # @param client [Schwab::Client, nil] Optional client instance
+      # @return [Hash] Price history data with candles
+      # @example Get 5 days of history
+      #   Schwab::MarketData.get_quote_history("AAPL", period_type: "day", period: 5)
+      def get_quote_history(symbol, period_type: nil, period: nil, frequency_type: nil,
+        frequency: nil, start_date: nil, end_date: nil,
+        need_extended_hours: true, need_previous_close: false, client: nil)
+        client ||= default_client
+        path = "/marketdata/v1/pricehistory"
+
+        params = { symbol: symbol }
+        params[:periodType] = period_type if period_type
+        params[:period] = period if period
+        params[:frequencyType] = frequency_type if frequency_type
+        params[:frequency] = frequency if frequency
+        params[:startDate] = format_timestamp(start_date) if start_date
+        params[:endDate] = format_timestamp(end_date) if end_date
+        params[:needExtendedHoursData] = need_extended_hours
+        params[:needPreviousClose] = need_previous_close
+
+        client.get(path, params)
+      end
+
+      # Get market movers for an index
+      #
+      # @param index [String] The index symbol (e.g., "$SPX", "$DJI")
+      # @param direction [String, nil] Direction of movement ("up" or "down")
+      # @param change [String, nil] Type of change ("percent" or "value")
+      # @param client [Schwab::Client, nil] Optional client instance
+      # @return [Hash] Market movers data
+      # @example Get top movers for S&P 500
+      #   Schwab::MarketData.get_movers("$SPX", direction: "up", change: "percent")
+      def get_movers(index, direction: nil, change: nil, client: nil)
+        client ||= default_client
+        path = "/marketdata/v1/movers/#{URI.encode_www_form_component(index)}"
+
+        params = {}
+        params[:direction] = direction if direction
+        params[:change] = change if change
+
+        client.get(path, params)
+      end
+
+      # Get market hours for one or more markets
+      #
+      # @param markets [String, Array<String>] Market(s) to get hours for (e.g., "EQUITY", "OPTION")
+      # @param date [Date, Time, String, nil] Date to get market hours for
+      # @param client [Schwab::Client, nil] Optional client instance
+      # @return [Hash] Market hours information
+      # @example Get equity market hours
+      #   Schwab::MarketData.get_market_hours("EQUITY")
+      def get_market_hours(markets, date: nil, client: nil)
+        client ||= default_client
+        params = {
+          markets: normalize_markets(markets),
+        }
+        params[:date] = format_date(date) if date
+
+        client.get("/marketdata/v1/markets", params)
+      end
+
+      # Get market hours for a single market
+      # Note: This appears to be the same endpoint as get_market_hours
+      # but with a single market instead of multiple
+      def get_market_hour(market_id, date: nil, client: nil)
+        get_market_hours(market_id, date: date, client: client)
+      end
+
+      private
+
+      def default_client
+        raise Error, "No client provided and no global configuration available" unless Schwab.configuration
+
+        @default_client ||= Client.new(
+          access_token: Schwab.configuration.access_token,
+          refresh_token: Schwab.configuration.refresh_token,
+        )
+      end
+
+      def normalize_symbols(symbols)
+        Array(symbols).join(",")
+      end
+
+      def normalize_fields(fields)
+        Array(fields).join(",")
+      end
+
+      def normalize_markets(markets)
+        Array(markets).join(",")
+      end
+
+      def format_timestamp(time)
+        case time
+        when Time, DateTime
+          (time.to_f * 1000).to_i
+        when Date
+          (time.to_time.to_f * 1000).to_i
+        when Integer
+          time
+        when String
+          (Time.parse(time).to_f * 1000).to_i
+        else
+          raise ArgumentError, "Invalid timestamp format: #{time.class}"
+        end
+      end
+
+      def format_date(date)
+        case date
+        when Date
+          date.strftime("%Y-%m-%d")
+        when Time, DateTime
+          date.strftime("%Y-%m-%d")
+        when String
+          Date.parse(date).strftime("%Y-%m-%d")
+        else
+          raise ArgumentError, "Invalid date format: #{date.class}"
+        end
+      end
+    end
+  end
+end

data/lib/schwab/middleware/authentication.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Schwab
+  module Middleware
+    # Faraday middleware for automatic token refresh
+    class TokenRefresh < Faraday::Middleware
+      def initialize(app, options = {})
+        super(app)
+        @access_token = options[:access_token]
+        @refresh_token = options[:refresh_token]
+        @client_id = options[:client_id]
+        @client_secret = options[:client_secret]
+        @on_token_refresh = options[:on_token_refresh]
+        @mutex = Mutex.new
+      end
+
+      # Process the request with automatic token refresh on 401
+      # @param env [Faraday::Env] The request environment
+      # @return [Faraday::Response] The response
+      def call(env)
+        # Add the current access token to the request
+        env[:request_headers]["Authorization"] = "Bearer #{@access_token}"
+
+        # Make the request
+        response = @app.call(env)
+
+        # Check if token expired (401 Unauthorized)
+        if response.status == 401 && @refresh_token
+          # Thread-safe token refresh
+          @mutex.synchronize do
+            # Double-check in case another thread already refreshed
+            if response.status == 401
+              refresh_access_token!
+
+              # Retry the request with new token
+              env[:request_headers]["Authorization"] = "Bearer #{@access_token}"
+              response = @app.call(env)
+            end
+          end
+        end
+
+        response
+      rescue Faraday::UnauthorizedError => e
+        # If we get an unauthorized error and have a refresh token, try refreshing
+        if @refresh_token
+          @mutex.synchronize do
+            refresh_access_token!
+
+            # Retry the request with new token
+            env[:request_headers]["Authorization"] = "Bearer #{@access_token}"
+            @app.call(env)
+          end
+        else
+          raise e
+        end
+      end
+
+      private
+
+      def refresh_access_token!
+        # Use the OAuth module to refresh the token
+        result = Schwab::OAuth.refresh_token(
+          refresh_token: @refresh_token,
+          client_id: @client_id,
+          client_secret: @client_secret,
+        )
+
+        # Update our tokens
+        @access_token = result[:access_token]
+        @refresh_token = result[:refresh_token] if result[:refresh_token]
+
+        # Call the callback if provided
+        @on_token_refresh&.call(result)
+
+        result
+      rescue => e
+        # If refresh fails, wrap the error with more context
+        raise Schwab::TokenExpiredError, "Failed to refresh access token: #{e.message}"
+      end
+    end
+
+    # Simple middleware for adding bearer token to requests
+    class Authentication < Faraday::Middleware
+      def initialize(app, token)
+        super(app)
+        @token = token
+      end
+
+      # Add bearer token to the request
+      # @param env [Faraday::Env] The request environment
+      # @return [Faraday::Response] The response
+      def call(env)
+        env[:request_headers]["Authorization"] = "Bearer #{@token}" if @token
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/schwab/middleware/rate_limit.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Schwab
+  # Middleware components for the HTTP client
+  module Middleware
+    # Faraday middleware for handling rate limits with exponential backoff
+    class RateLimit < Faraday::Middleware
+      # Default maximum number of retries for rate-limited requests
+      DEFAULT_MAX_RETRIES = 3
+      # Default initial retry delay in seconds
+      DEFAULT_RETRY_DELAY = 1 # seconds
+      # Default exponential backoff factor for retries
+      DEFAULT_BACKOFF_FACTOR = 2
+      RETRY_STATUSES = [429, 503].freeze # Rate limited and Service Unavailable
+
+      def initialize(app, options = {})
+        super(app)
+        @max_retries = options[:max_retries] || DEFAULT_MAX_RETRIES
+        @retry_delay = options[:retry_delay] || DEFAULT_RETRY_DELAY
+        @backoff_factor = options[:backoff_factor] || DEFAULT_BACKOFF_FACTOR
+        @logger = options[:logger]
+      end
+
+      # Process the request with rate limit handling
+      # @param env [Faraday::Env] The request environment
+      # @return [Faraday::Response] The response
+      def call(env)
+        retries = 0
+        delay = @retry_delay
+
+        begin
+          response = @app.call(env)
+
+          # Check if we should retry this response
+          if should_retry?(response) && retries < @max_retries
+            retries += 1
+
+            # Check for Retry-After header
+            retry_after = response.headers["retry-after"]
+            wait_time = retry_after ? parse_retry_after(retry_after) : delay
+
+            log_retry(env, response, retries, wait_time)
+
+            # Wait before retrying
+            sleep(wait_time)
+
+            # Exponential backoff for next retry
+            delay *= @backoff_factor
+
+            # Retry the request by raising a custom error
+            raise Faraday::RetriableResponse.new(nil, response)
+          end
+
+          response
+        rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+          # Retry on network errors
+          if retries < @max_retries
+            retries += 1
+
+            log_retry_error(env, e, retries, delay)
+
+            sleep(delay)
+            delay *= @backoff_factor
+
+            retry
+          else
+            raise e
+          end
+        rescue Faraday::RetriableResponse
+          # This is our custom retry signal
+          retry
+        end
+      end
+
+      private
+
+      def should_retry?(response)
+        RETRY_STATUSES.include?(response.status)
+      end
+
+      def parse_retry_after(value)
+        # Retry-After can be in seconds (integer) or HTTP date
+        if value.match?(/^\d+$/)
+          value.to_i
+        else
+          # Parse HTTP date and calculate seconds to wait
+          retry_time = Time.httpdate(value)
+          wait_seconds = retry_time - Time.now
+          wait_seconds > 0 ? wait_seconds : @retry_delay
+        end
+      rescue ArgumentError
+        # If we can't parse it, use default delay
+        @retry_delay
+      end
+
+      def log_retry(env, response, attempt, wait_time)
+        return unless @logger
+
+        @logger.info(
+          "[RateLimit] Retrying request to #{env[:url].path} " \
+            "(attempt #{attempt}/#{@max_retries}, status: #{response.status}, " \
+            "waiting: #{wait_time}s)",
+        )
+      end
+
+      def log_retry_error(env, error, attempt, wait_time)
+        return unless @logger
+
+        @logger.info(
+          "[RateLimit] Retrying request to #{env[:url].path} after error " \
+            "(attempt #{attempt}/#{@max_retries}, error: #{error.class}, " \
+            "waiting: #{wait_time}s)",
+        )
+      end
+    end
+  end
+end