schwab_rb 0.6.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 123cd13fd78778da2f5f2d08f9dc8f7594a07b8fcd93659bd49df3b1cd28ddb7
-  data.tar.gz: 0760e50de57a1a2d207cf1cc4744441f4a08fc2fc983859317feda22df701b15
+  metadata.gz: e92f8e69c61f92f34a54eb5ae7b5b07a8734dbe71a221006972a0988aedc5fd5
+  data.tar.gz: a0635b9f44605a22ee31140f8b8601d7f0cf64d28dcdf41e5f711d680efa7dfd
 SHA512:
-  metadata.gz: bc5b094add1c5002f1a799ef41ca023b18e3857c39476c91282174640728fd7be0fe8f7de59a265cdf7c86a893a0c04dce91f7fb7551ee2818a5e371f9b1f792
-  data.tar.gz: f29fc656583df33e6ff787715713075fb0ffc094ca5ae81915fb37fca4c0dbbefa362488a687f6dcc9dd957dd65c65917b66ba98fc4401467139adf68ea03f4a
+  metadata.gz: c30b898de7b8e933960f38c62b82364210ec89abe603b773bf7e0b012e74ce8e3230f6f28c015fc100a46a2a1a7596e6896758f3a695dd9707c63ef92eb1df8d
+  data.tar.gz: 8f0e880a9a0227ad9b02c1d8ed95f9b66d49e2303ac5ad955f8cd9cc7fa0cabd893e72a5091f6990c352eacf5939e9a75eee292cf0f592dbe7c74b53baff897c

data/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr edit:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

data/.codex/skills/schwab-rb-cli/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: schwab-rb-cli
+description: Use the installed schwab_rb CLI for authentication and price history downloads. Activate when a user wants to run the schwab_rb command, log in to Schwab, fetch market data, troubleshoot CLI installation or environment variables, or save price history from the command line.
+---
+
+# Schwab RB CLI Skill
+
+Use this skill when the task should be completed through the installed `schwab_rb` command rather than by editing Ruby code directly.
+
+## When to use
+
+- The user wants to run `schwab_rb help`, `schwab_rb login`, or `schwab_rb price-history`
+- The user wants to download price history data to JSON or CSV
+- The user needs help with CLI installation, `asdf` shims, or missing `SCHWAB_*` environment variables
+- The user wants the agent to verify the CLI works on the local machine
+
+## Quick workflow
+
+1. Prefer the bundled wrapper script:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh help
+```
+
+The wrapper only attempts to execute the globally installed `schwab_rb` command from `PATH`. It does not use repo-relative paths or Bundler fallbacks.
+
+2. If the wrapper reports that `schwab_rb` is missing:
+   - Report that the host machine does not have the CLI available in `PATH`
+   - Tell the user to install the gem globally and fix shell/shim configuration before retrying
+
+3. Before running auth or data commands, verify these exported variables exist in the shell environment:
+   - `SCHWAB_API_KEY`
+   - `SCHWAB_APP_SECRET`
+   - `SCHWAB_APP_CALLBACK_URL`
+
+4. For first-time auth, run:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh login
+```
+
+5. For data downloads, run:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh price-history --symbol AAPL --start-date 2026-03-01
+```
+
+## Operating guidance
+
+- Do not ask users to paste secrets into chat when the task can be completed using already-exported environment variables.
+- Assume the CLI token is shared at `~/.schwab_rb/token.json`.
+- Assume downloaded data goes to `~/.schwab_rb/data` unless `--dir` is passed.
+- Use `--format csv` only when the user specifically wants flat files; otherwise prefer JSON because it matches the API response shape.
+- If the wrapper says the executable is missing, stop and report that the host install is unavailable. Do not substitute repo-local execution.
+- If the CLI reports missing environment variables, check exported shell envs first. Do not rely on a repo-local `.env` unless the user explicitly wants that setup.
+
+## References
+
+- For concrete commands and troubleshooting steps, read [references/cli_examples.md](references/cli_examples.md).

data/.codex/skills/schwab-rb-cli/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "schwab_rb CLI"
+  short_description: "Run the installed schwab_rb CLI for auth and market data downloads"

data/.codex/skills/schwab-rb-cli/references/cli_examples.md

@@ -0,0 +1,100 @@
+# schwab_rb CLI Examples
+
+## Basic checks
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh help
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh help price-history
+```
+
+## Authentication
+
+Expected exported variables:
+
+```bash
+env | rg '^SCHWAB_'
+```
+
+Login flow:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh login
+```
+
+## Price history downloads
+
+Daily JSON output:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh price-history --symbol AAPL --start-date 2026-03-01
+```
+
+Minute CSV output:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh price-history \
+  --symbol VIX \
+  --start-date 2026-03-01 \
+  --end-date 2026-03-24 \
+  --freq 1min \
+  --format csv
+```
+
+Custom output directory:
+
+```bash
+skills/schwab-rb-cli/scripts/run_schwab_rb.sh price-history \
+  --symbol SPY \
+  --start-date 2026-03-01 \
+  --dir /tmp/schwab_rb_data
+```
+
+## Installation troubleshooting
+
+Install the gem from the repo:
+
+```bash
+bundle exec rake install
+```
+
+If the host uses `asdf`, regenerate shims:
+
+```bash
+asdf reshim ruby 3.2.2
+```
+
+Verify the executable:
+
+```bash
+which schwab_rb
+ls -l ~/.asdf/shims/schwab_rb
+```
+
+If `schwab_rb` is still not on `PATH`, the wrapper script will fail immediately and the agent should report that the host install is not usable yet.
+
+## Environment troubleshooting
+
+Check that the variables are exported, not just set in the shell:
+
+```bash
+env | rg '^SCHWAB_'
+```
+
+Portable shell setup:
+
+```bash
+# ~/.zshrc
+if [ -f "$HOME/.env" ]; then
+  set -a
+  source "$HOME/.env"
+  set +a
+fi
+```
+
+Then in `~/.env`:
+
+```bash
+SCHWAB_API_KEY=...
+SCHWAB_APP_SECRET=...
+SCHWAB_APP_CALLBACK_URL=https://127.0.0.1:8182
+```

data/.codex/skills/schwab-rb-cli/scripts/run_schwab_rb.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v schwab_rb >/dev/null 2>&1; then
+  exec "$(command -v schwab_rb)" "$@"
+fi
+
+echo "schwab_rb executable not found in PATH. Install the gem globally on the host machine and ensure the executable is available before using this skill." >&2
+exit 1

data/AGENTS.md

@@ -0,0 +1,137 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.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/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+### Added
+- CLI `sample` command for saving single-expiration option chain snapshots as CSV or JSON
+- `--root` option for filtering sampled contracts by option root and using that root in output filenames
+
+### Changed
+- CLI history downloads now default to `~/.schwab_rb/data/history`
+- CLI option samples now default to `~/.schwab_rb/data/options`
+
 ## [0.6.0] - 2025-12-11
 
 ### Breaking Changes

data/README.md

@@ -18,6 +18,44 @@ gem install schwab_rb
 
 Note: The gem requires Ruby 3.0.0 or higher.
 
+## CLI
+
+Installing the gem also installs a `schwab_rb` executable.
+
+Set these environment variables before using the CLI:
+
+```bash
+export SCHWAB_API_KEY=your_api_key_here
+export SCHWAB_APP_SECRET=your_app_secret_here
+export SCHWAB_APP_CALLBACK_URL=https://127.0.0.1:8182
+```
+
+Authenticate once to create the shared token in `~/.schwab_rb/token.json`:
+
+```bash
+schwab_rb login
+```
+
+Download price history into `~/.schwab_rb/data` as JSON. Files are stored per symbol and frequency, for example `AAPL_day.json` or `SPX_5min.csv`, and the CLI reuses and reconciles existing candle files when possible:
+
+```bash
+schwab_rb price-history --symbol AAPL --start-date 2026-03-01
+```
+
+Write CSV output to a custom directory:
+
+```bash
+schwab_rb price-history \
+  --symbol VIX \
+  --start-date 2026-03-01 \
+  --end-date 2026-03-24 \
+  --freq 1min \
+  --format csv \
+  --dir ./tmp/price_history
+```
+
+That command writes `./tmp/price_history/VIX_1min.csv`.
+
 ## Prerequisites
 
 Before using this gem, you'll need:
@@ -268,4 +306,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jwplat
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-The gem is inspired by [schwab-py](https://pypi.org/project/schwab-py). The original implementation can be found [here](https://github.com/alexgolec/schwab-py).
+The gem is inspired by [schwab-py](https://pypi.org/project/schwab-py). The original implementation can be found [here](https://github.com/alexgolec/schwab-py).

data/Rakefile

@@ -3,6 +3,32 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+gem_helper = Bundler::GemHelper.instance
+
+def install_built_gem(gem_helper, local: false)
+  gem_path = File.join(
+    gem_helper.base,
+    "pkg",
+    "#{gem_helper.send(:name)}-#{gem_helper.send(:version)}.gem"
+  )
+  command = [*gem_helper.send(:gem_command), "install", gem_path, "--no-document"]
+  command << "--local" if local
+  sh(*command)
+  Bundler.ui.confirm "#{gem_helper.send(:name)} (#{gem_helper.send(:version)}) installed."
+end
+
+Rake::Task["install"].clear
+desc "Build and install the gem into system gems without generating documentation."
+task "install" => "build" do
+  install_built_gem(gem_helper)
+end
+
+Rake::Task["install:local"].clear
+desc "Build and install the gem into system gems without network access or documentation."
+task "install:local" => "build" do
+  install_built_gem(gem_helper, local: true)
+end
+
 RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"

data/doc/LOGGING.md

@@ -0,0 +1,141 @@
+# Logging Configuration
+
+The `schwab_rb` gem provides flexible logging configuration options to suit different development and production needs.
+
+## Overview
+
+The gem's logging system is built around two main components:
+- `SchwabRb::Configuration` - Manages configuration settings
+- `SchwabRb::Logger` - Creates and manages the logger instance
+
+## Configuration Methods
+
+### 1. Environment Variables
+
+Set logging behavior using environment variables:
+
+```bash
+export SCHWAB_LOGFILE="/path/to/logfile.log"  # File path or "STDOUT"
+export SCHWAB_LOG_LEVEL="INFO"               # DEBUG, INFO, WARN, ERROR, FATAL
+```
+
+### 2. Programmatic Configuration
+
+Configure logging in your Ruby code:
+
+```ruby
+SchwabRb.configure do |config|
+  config.log_file = "/path/to/logfile.log"
+  config.log_level = "DEBUG"
+  config.silence_output = false
+end
+```
+
+## Using the Gem's Built-in Logger
+
+### Default Behavior
+By default, the gem creates its own logger that:
+- Logs to STDOUT
+- Uses WARN level
+- Rotates log files weekly (when logging to file)
+- Uses custom formatting: `[HH:MM:SS] SCHWAB_RB LEVEL: message`
+
+### Example Configuration
+```ruby
+SchwabRb.configure do |config|
+  config.log_file = "/var/log/schwab_rb.log"
+  config.log_level = "INFO"
+end
+```
+
+## Using an External Logger
+
+You can provide your own logger instance instead of using the gem's built-in logger:
+
+### Rails Logger Example
+```ruby
+# In Rails application
+SchwabRb.configure do |config|
+  config.logger = Rails.logger
+end
+```
+
+### Custom Logger Example
+```ruby
+# Custom logger with specific formatting
+my_logger = Logger.new(STDOUT)
+my_logger.level = Logger::DEBUG
+my_logger.formatter = proc do |severity, datetime, progname, msg|
+  "#{datetime} [SCHWAB] #{severity}: #{msg}\n"
+end
+
+SchwabRb.configure do |config|
+  config.logger = my_logger
+end
+```
+
+### Structured Logging Example
+```ruby
+# Using a structured logging library
+require 'semantic_logger'
+
+SchwabRb.configure do |config|
+  config.logger = SemanticLogger['SchwabRb']
+end
+```
+
+## Logger Behavior
+
+### External Logger Priority
+When an external logger is provided via `config.logger`, it takes precedence over all other settings. The gem will:
+- Use your logger instance directly
+- Ignore `log_file` and `log_level` settings
+- Not apply custom formatting
+
+### Silence Output
+Setting `silence_output = true` creates a null logger that discards all messages:
+
+```ruby
+SchwabRb.configure do |config|
+  config.silence_output = true
+end
+```
+
+### Log File Handling
+When logging to a file, the gem:
+- Creates the directory if it doesn't exist
+- Creates the log file if it doesn't exist
+- Rotates logs weekly
+- Returns a null logger if the path is `:null` or `"/dev/null"`
+
+## Log Levels
+
+Available log levels (case-insensitive):
+- `DEBUG` - Detailed information for debugging
+- `INFO` - General information messages
+- `WARN` - Warning messages (default)
+- `ERROR` - Error conditions
+- `FATAL` - Critical errors
+
+## Accessing the Logger
+
+Get the configured logger instance:
+
+```ruby
+logger = SchwabRb::Logger.logger
+logger.info("Custom log message")
+```
+
+## Configuration Reset
+
+Reset the logger and configuration:
+
+```ruby
+# Reset configuration to defaults
+SchwabRb.reset_configuration!
+
+# Reset logger instance (forces recreation)
+SchwabRb::Logger.reset!
+```
+
+Note: The logger is automatically reset when configuration changes are made via `SchwabRb.configure`.

data/doc/QUICK_START.md

@@ -33,6 +33,12 @@ SCHWAB_APP_CALLBACK_URL=https://127.0.0.1:8182
 SCHWAB_TOKEN_PATH=~/.schwab_rb/token.json
 ```
 
+Or authenticate with the CLI:
+
+```bash
+schwab_rb login
+```
+
 ## 4. Initialize Client (First Time)
 
 ```ruby
@@ -70,6 +76,15 @@ accounts.each do |account|
 end
 ```
 
+Or download price history directly from the CLI:
+
+```bash
+schwab_rb price-history --symbol AAPL --start-date 2026-03-01
+schwab_rb price-history --symbol VIX --start-date 2026-03-01 --end-date 2026-03-24 --freq 1min --format csv
+```
+
+The CLI stores candle files using `SYMBOL_FREQ.format`, such as `AAPL_day.json` or `VIX_1min.csv`, and will reuse an existing file instead of re-downloading ranges it already has.
+
 ## 6. Set Up Account Names (Optional but Recommended)
 
 Create `~/.schwab_rb/account_names.json`:

data/exe/schwab_rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dotenv/load"
+require "schwab_rb"
+
+exit SchwabRb::CLI::App.new.call(ARGV.dup)

data/lib/schwab_rb/auth/init_client_easy.rb

@@ -3,6 +3,7 @@
 require "oauth2"
 require_relative "init_client_token_file"
 require_relative "init_client_login"
+require_relative "../path_support"
 
 module SchwabRb
   module Auth
@@ -17,6 +18,7 @@ module SchwabRb
       interactive: true,
       requested_browser: nil
     )
+      token_path = SchwabRb::PathSupport.expand_path(token_path)
 
       raise OAuth2::Error, "No token found" unless File.exist?(token_path)
 

data/lib/schwab_rb/auth/init_client_login.rb

@@ -5,6 +5,7 @@ require "uri"
 require "net/http"
 require "json"
 require "oauth2"
+require_relative "../path_support"
 # require 'logger'
 
 module SchwabRb
@@ -71,6 +72,7 @@ module SchwabRb
       interactive: true,
       requested_browser: nil
     )
+      token_path = SchwabRb::PathSupport.expand_path(token_path)
 
       callback_timeout = if !callback_timeout
                            0

data/lib/schwab_rb/auth/init_client_token_file.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require "oauth2"
+require_relative "../path_support"
 
 module SchwabRb
   module Auth
     def self.init_client_token_file(api_key, app_secret, token_path, enforce_enums: true)
+      token_path = SchwabRb::PathSupport.expand_path(token_path)
+
       oauth = OAuth2::Client.new(
         api_key,
         app_secret,

data/lib/schwab_rb/auth/token_manager.rb

@@ -2,12 +2,15 @@
 
 require "oauth2"
 require "json"
+require_relative "../constants"
+require_relative "../path_support"
 
 module SchwabRb
   module Auth
     class TokenManager
       class << self
         def from_file(token_path)
+          token_path = SchwabRb::PathSupport.expand_path(token_path)
           token_data = JSON.parse(File.read(token_path))
           token = SchwabRb::Auth::Token.new(
             token: token_data["token"]["access_token"],
@@ -40,7 +43,7 @@ module SchwabRb
       def initialize(token, timestamp, token_path: SchwabRb::Constants::DEFAULT_TOKEN_PATH)
         @token = token
         @timestamp = timestamp
-        @token_path = token_path
+        @token_path = SchwabRb::PathSupport.expand_path(token_path)
       end
 
       attr_reader :token, :timestamp, :token_path
@@ -77,6 +80,7 @@ module SchwabRb
       end
 
       def to_file
+        SchwabRb::PathSupport.ensure_parent_directory(token_path)
         File.write(token_path, to_json)
       end