schwab_rb 0.3.12 → 0.4.0

data/doc/QUICK_START.md

@@ -0,0 +1,239 @@
+# Quick Start Guide
+
+Get started with schwab_rb in 5 minutes.
+
+## 1. Install
+
+```bash
+gem install schwab_rb
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'schwab_rb'
+```
+
+## 2. Get Your Schwab API Credentials
+
+1. Go to [Schwab Developer Portal](https://developer.schwab.com/)
+2. Create an app to get:
+   - **API Key** (App Key)
+   - **App Secret** (Secret)
+   - **Callback URL** (use `https://127.0.0.1:8182` for local development)
+
+## 3. Set Up Environment Variables
+
+Create a `.env` file:
+
+```bash
+SCHWAB_API_KEY=your_api_key_here
+SCHWAB_APP_SECRET=your_app_secret_here
+SCHWAB_APP_CALLBACK_URL=https://127.0.0.1:8182
+SCHWAB_TOKEN_PATH=~/.schwab_rb/token.json
+```
+
+## 4. Initialize Client (First Time)
+
+```ruby
+require 'schwab_rb'
+require 'dotenv/load'
+
+# This will open your browser for authentication
+client = SchwabRb::Auth.init_client_easy(
+  ENV['SCHWAB_API_KEY'],
+  ENV['SCHWAB_APP_SECRET'],
+  ENV['SCHWAB_APP_CALLBACK_URL'],
+  ENV['SCHWAB_TOKEN_PATH']
+)
+
+puts "✓ Authenticated successfully!"
+```
+
+**What happens:**
+- Browser opens to Schwab login
+- You log in and authorize
+- Token saved to `~/.schwab_rb/token.json`
+- Client ready to use!
+
+## 5. Make Your First API Call
+
+```ruby
+# Get your accounts
+accounts = client.get_accounts
+
+accounts.each do |account|
+  puts "Account: #{account.account_number}"
+  puts "Type: #{account.type}"
+  puts "Value: $#{account.balance.total_value}"
+  puts "---"
+end
+```
+
+## 6. Set Up Account Names (Optional but Recommended)
+
+Create `~/.schwab_rb/account_names.json`:
+
+```json
+{
+  "my_trading": "12345678",
+  "my_ira": "87654321"
+}
+```
+
+Populate account hashes:
+
+```ruby
+client.get_account_numbers
+```
+
+Now use friendly names:
+
+```ruby
+# Instead of:
+# account = client.get_account("ABC123HASH")
+
+# Do this:
+account = client.get_account(account_name: "my_trading")
+```
+
+## Common Operations
+
+### Get Account Info
+
+```ruby
+account = client.get_account(account_name: "my_trading")
+puts "Buying Power: $#{account.balance.buying_power}"
+```
+
+### Get Quotes
+
+```ruby
+quote = client.get_quote("AAPL")
+puts "#{quote.symbol}: $#{quote.last_price}"
+```
+
+### Get Price History
+
+```ruby
+history = client.get_price_history_every_day(
+  "AAPL",
+  start_datetime: DateTime.now - 30
+)
+
+puts "#{history.candles.size} days of data"
+history.candles.last(5).each do |candle|
+  puts "#{candle.date}: $#{candle.close}"
+end
+```
+
+### Place Order (Market Buy)
+
+```ruby
+order = SchwabRb::Orders::Builder.new
+  .set_session(:normal)
+  .set_duration(:day)
+  .set_order_type(:market)
+  .add_equity_leg(:buy, 'AAPL', 10)
+  .build
+
+response = client.place_order(order, account_name: "my_trading")
+puts "Order placed!"
+```
+
+### Get Orders
+
+```ruby
+orders = client.get_account_orders(account_name: "my_trading")
+
+orders.each do |order|
+  puts "#{order.status}: #{order.order_leg_collection.first.quantity} shares of #{order.order_leg_collection.first.instrument.symbol}"
+end
+```
+
+### Get Transactions
+
+```ruby
+transactions = client.get_transactions(
+  account_name: "my_trading",
+  start_date: DateTime.now - 7
+)
+
+puts "#{transactions.size} transactions in the last week"
+```
+
+## Configuration (Optional)
+
+```ruby
+SchwabRb.configure do |config|
+  # Logging
+  config.log_level = "INFO"
+  config.log_file = "schwab.log"
+
+  # Account management
+  config.schwab_home = "~/.schwab_rb"
+  config.account_names_path = "~/.schwab_rb/account_names.json"
+  config.account_hashes_path = "~/.schwab_rb/account_hashes.json"
+end
+```
+
+## Next Steps
+
+- **Trading**: See [examples/](../examples/) for order placement examples
+- **Account Management**: Read [ACCOUNT_MANAGEMENT.md](./ACCOUNT_MANAGEMENT.md) for multi-account setup
+- **API Reference**: Check the [main README](../README.md) for complete API documentation
+
+## Troubleshooting
+
+**Authentication fails?**
+- Check your API credentials
+- Make sure callback URL matches exactly
+- Try deleting `~/.schwab_rb/token.json` and re-authenticating
+
+**Token expired?**
+- The client automatically refreshes tokens
+- If issues persist, re-authenticate with `init_client_easy`
+
+**Can't find account?**
+- Run `client.get_account_numbers` to refresh account hashes
+- Check `account_names.json` for typos
+- Use `client.available_account_names` to see configured accounts
+
+## Example Script
+
+```ruby
+#!/usr/bin/env ruby
+require 'schwab_rb'
+require 'dotenv/load'
+
+# Initialize
+client = SchwabRb::Auth.init_client_easy(
+  ENV['SCHWAB_API_KEY'],
+  ENV['SCHWAB_APP_SECRET'],
+  ENV['SCHWAB_APP_CALLBACK_URL'],
+  ENV['SCHWAB_TOKEN_PATH']
+)
+
+# Get available accounts
+names = client.available_account_names
+puts "Available accounts: #{names.join(', ')}"
+
+# Check account balance
+account = client.get_account(account_name: names.first)
+puts "\n#{names.first}:"
+puts "  Total Value: $#{account.balance.total_value}"
+puts "  Cash: $#{account.balance.cash_balance}"
+puts "  Buying Power: $#{account.balance.buying_power}"
+
+# Get a quote
+quote = client.get_quote("SPY")
+puts "\nSPY: $#{quote.last_price}"
+
+puts "\n✓ All done!"
+```
+
+---
+
+**Need Help?**
+- Check the [main README](../README.md)
+- Review [examples/](../examples/)

data/examples/place_oco_order.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'schwab_rb'
+require 'dotenv'
+require 'pry'
+
+Dotenv.load
+
+# Example: Place an OCO (One Cancels Another) order
+#
+# This example demonstrates how to create an OCO order where two orders
+# are submitted simultaneously, and if one fills, the other is automatically cancelled.
+#
+
+# SchwabRb::Configuration.configure do |config|
+# end
+
+CURRENT_ACCT = "TRADING_BROKERAGE_ACCOUNT"
+acct_manager = SchwabRb::AccountHashManager.new
+
+client = SchwabRb::Auth.init_client_easy(
+  ENV['SCHWAB_API_KEY'],
+  ENV['SCHWAB_APP_SECRET'],
+  ENV['SCHWAB_APP_CALLBACK_URL'],
+  ENV['SCHWAB_TOKEN_PATH']
+)
+
+puts "Example 1: OCO order with take profit and stop loss"
+puts "=" * 60
+
+
+symbols = [
+  "SPXW  251020P06510000", # long put
+  "SPXW  251020P06530000", # short put
+  "SPXW  251020C06790000", # long call
+  "SPXW  251020C06770000",  # short call
+]
+
+oco_order = SchwabRb::Orders::OrderFactory.build(
+  strategy_type: SchwabRb::Order::OrderStrategyTypes::OCO,
+  child_order_specs: [
+    {
+      strategy_type: SchwabRb::Order::ComplexOrderStrategyTypes::VERTICAL,
+      short_leg_symbol: "SPXW  251020P06530000",
+      long_leg_symbol: "SPXW  251020P06510000",
+      order_type: SchwabRb::Order::Types::STOP_LIMIT,
+      price: 2.1,
+      stop_price: 2.0,
+      order_instruction: :close,
+      credit_debit: :debit,
+      quantity: 2
+    },
+    {
+      strategy_type: SchwabRb::Order::ComplexOrderStrategyTypes::VERTICAL,
+      short_leg_symbol: "SPXW  251020C06770000",
+      long_leg_symbol: "SPXW  251020C06790000",
+      order_type: SchwabRb::Order::Types::STOP_LIMIT,
+      price: 2.1,
+      stop_price: 2.0,
+      order_instruction: :close,
+      credit_debit: :debit,
+      quantity: 2
+    }
+  ]
+)
+
+built_order = oco_order.build
+
+binding.pry
+
+response = client.place_order(built_order, account_name: CURRENT_ACCT)
+
+binding.pry

data/lib/schwab_rb/account_hash_manager.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module SchwabRb
+  class AccountHashManager
+    class AccountNamesFileNotFoundError < StandardError; end
+    class InvalidAccountNamesFileError < StandardError; end
+
+    attr_reader :account_names_path, :account_hashes_path, :account_names
+
+    def initialize(account_names_path = nil, account_hashes_path = nil)
+      @account_names_path = account_names_path || SchwabRb.configuration.account_names_path
+      @account_hashes_path = account_hashes_path || SchwabRb.configuration.account_hashes_path
+      @account_names_path = File.expand_path(@account_names_path)
+      @account_hashes_path = File.expand_path(@account_hashes_path)
+      @account_names = []
+    end
+
+    def update_hashes_from_api_response(account_numbers_response)
+      account_names = load_account_names
+      current_hashes = load_account_hashes
+
+      number_to_hash = {}
+      account_numbers_response.each do |account_data|
+        account_number = account_data[:accountNumber]
+        hash_value = account_data[:hashValue]
+        number_to_hash[account_number] = hash_value
+      end
+
+      updated_hashes = {}
+      missing_accounts = []
+
+      account_names.each do |name, account_number|
+        if number_to_hash.key?(account_number)
+          updated_hashes[name] = number_to_hash[account_number]
+        elsif current_hashes.key?(name)
+          # Keep existing hash but warn that account wasn't in API response
+          updated_hashes[name] = current_hashes[name]
+          missing_accounts << { name: name, number: account_number }
+        else
+          # Account name exists but no hash found (new or invalid account)
+          missing_accounts << { name: name, number: account_number }
+        end
+      end
+
+      # Log warnings for accounts that weren't found in API response
+      if missing_accounts.any?
+        missing_accounts.each do |account|
+          SchwabRb::Logger.logger.warn(
+            "Account '#{account[:name]}' (#{account[:number]}) not found in API response. " \
+            "This may indicate a closed account or incorrect account number in account_names.json"
+          )
+        end
+      end
+
+      save_account_hashes(updated_hashes)
+      updated_hashes
+    end
+
+    def get_hash_by_name(account_name)
+      hashes = load_account_hashes
+      hashes[account_name]
+    end
+
+    def get_all_hashes
+      load_account_hashes
+    end
+
+    def available_account_names
+      begin
+        load_account_names.keys
+      rescue AccountNamesFileNotFoundError
+        []
+      end
+    end
+
+    private
+
+    def load_account_hashes
+      return {} unless File.exist?(@account_hashes_path)
+
+      begin
+        json_content = File.read(@account_hashes_path)
+        JSON.parse(json_content)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
+    def save_account_hashes(hashes_map)
+      FileUtils.mkdir_p(File.dirname(@account_hashes_path))
+
+      File.write(@account_hashes_path, JSON.pretty_generate(hashes_map))
+    end
+
+    def load_account_names
+      unless File.exist?(@account_names_path)
+        raise AccountNamesFileNotFoundError,
+              "Account names file not found at #{@account_names_path}. " \
+              "Please create a JSON file mapping account names to account numbers. " \
+              "Example: {\"my_trading_account\": \"12345678\", \"my_ira\": \"87654321\"}"
+      end
+
+      begin
+        json_content = File.read(@account_names_path)
+        return {} if json_content.strip.empty?
+
+        account_names_hash = JSON.parse(json_content)
+        @account_names = account_names_hash.keys
+        account_names_hash
+      rescue JSON::ParserError => e
+        raise InvalidAccountNamesFileError,
+              "Invalid JSON in account names file at #{@account_names_path}: #{e.message}"
+      end
+    end
+  end
+end