schwab_rb 0.3.12 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b051569d86c70eaf117260fdc77f1926eb7c0bdf1141614903ac02f4bd834e6f
-  data.tar.gz: 3d7f8e02b966002399f23faba75559561827e080d13257da36f219cef2019464
+  metadata.gz: 9855a77823d8f9039e402281cec2efba85bd1bdba9b7ff7404a8ad136a276631
+  data.tar.gz: fd0c1e0cc43e9c52c82e8f45fee14c919ea307b40c82195d8272ce921ca5defd
 SHA512:
-  metadata.gz: 7076466bc502788b935e4fa239f44624a27c0a066c6b78be76af798efaa1181720710cd0b796b67a5a1003aac1d5b070739942a7cbed4b8daa0fe87b0c45bf01
-  data.tar.gz: 272af18823441bc12f778213d9c2589e7f35b0001f349b72b8df47ac0ae2d9f65aa8c30e3088aadc78c774b479ceed72a474ccdd762c6486f4db99c447dfb746
+  metadata.gz: 1cd4e54dc2eace5a02ce328762f3ffaa4f23356684716d8d4987268c63d463b4cacbd51c8f278ec42cee8a73005bacd11a150db8e78beba3e34ae84c35e9e86e
+  data.tar.gz: 0b3f8920a5fd5c6256e5a3d69da6a65d54a781e8773b0a1a8981f88418444d2ee1243060f73b5c57dc4f63f61eea14aa420fcae57a70c98d5a0c0ed02929c7dd

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.4.0] - 2025-10-19
+
+### Added
+- Account Management System: New `AccountHashManager` class for managing accounts via friendly names instead of encrypted account hashes
+- One-Cancels-Other (OCO) Orders: Support for OCO order types with comprehensive examples
+- Stop Limit Orders: Added support for stop limit order types
+- Order type and duration as configurable parameters across all order types
+- Quick Start Guide (doc/QUICK_START.md) for new users
+- Account Management documentation (doc/ACCOUNT_MANAGEMENT.md) with detailed usage examples
+- Place Order Samples documentation (doc/PLACE_ORDER_SAMPLES.md) with examples for all order types
+- Example script for placing OCO orders (examples/place_oco_order.rb)
+- Configuration options for account management paths
+
+### Changed
+- Enhanced `BaseClient` with account name resolution - client methods can now accept account names or hashes
+- Refactored order classes (IronCondorOrder, VerticalOrder, SingleOrder) to support order_type and duration parameters
+- Improved `OrderFactory` to handle OCO and stop limit orders
+- Updated bin/console with account hash manager initialization
+
+### Fixed
+- Fixed parameter order in client method calls
+
 ## [0.2.0] - 2025-07-20
 
 ### Added

data/doc/ACCOUNT_MANAGEMENT.md

@@ -0,0 +1,297 @@
+# Account Management Guide
+
+The schwab_rb gem provides a secure and convenient way to manage multiple Schwab accounts using friendly account names instead of exposing account numbers or hashes in your code.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Account Names Setup](#account-names-setup)
+- [Using Account Names](#using-account-names)
+- [Security Best Practices](#security-best-practices)
+- [Troubleshooting](#troubleshooting)
+- [API Reference](#api-reference)
+
+## Overview
+
+Schwab's API requires account hashes for most operations, which:
+- Change periodically (accounts get "rehashed")
+- Are inconvenient to look up and copy
+- Expose sensitive account numbers in code
+
+schwab_rb provides an account name mapping system that:
+- **Increases Security**: Account numbers never appear in your code
+- **Improves Usability**: Reference accounts by friendly names like "my_trading_account"
+- **Auto-Updates**: Account hashes refresh automatically
+- **Handles Staleness**: Retries failed requests with fresh hashes
+
+## Quick Start
+
+### 1. Create Account Names File
+
+Create `~/.schwab_rb/account_names.json` with your account mappings:
+
+```json
+{
+  "my_trading_account": "12345678",
+  "my_ira": "87654321",
+  "my_roth_ira": "11223344"
+}
+```
+
+### 2. Initialize Client and Fetch Hashes
+
+```ruby
+require "schwab_rb"
+
+# Initialize client
+client = SchwabRb::Auth.init_client_easy(
+  ENV['SCHWAB_API_KEY'],
+  ENV['SCHWAB_APP_SECRET'],
+  ENV['SCHWAB_APP_CALLBACK_URL'],
+  ENV['SCHWAB_TOKEN_PATH']
+)
+
+# Fetch account numbers and populate hashes
+client.get_account_numbers
+```
+
+This automatically creates `~/.schwab_rb/account_hashes.json` with the name-to-hash mappings.
+
+### 3. Use Account Names in API Calls
+
+```ruby
+# Get account by name
+account = client.get_account(account_name: "my_trading_account")
+
+# Place order using account name
+order = client.place_order(order_spec, account_name: "my_ira")
+
+# Get transactions
+transactions = client.get_transactions(account_name: "my_roth_ira")
+```
+
+## Configuration
+
+### Default Paths
+
+By default, schwab_rb uses:
+- `schwab_home`: `~/.schwab_rb`
+- `account_hashes_path`: `~/.schwab_rb/account_hashes.json`
+- `account_names_path`: `~/.schwab_rb/account_names.json`
+
+### Custom Paths
+
+#### Via Environment Variables
+
+```bash
+export SCHWAB_HOME="/custom/path"
+export SCHWAB_ACCOUNT_HASHES_PATH="/custom/path/hashes.json"
+export SCHWAB_ACCOUNT_NAMES_PATH="/custom/path/names.json"
+```
+
+#### Via Ruby Configuration
+
+```ruby
+SchwabRb.configure do |config|
+  config.schwab_home = "/custom/path"
+  config.account_hashes_path = "/custom/path/hashes.json"
+  config.account_names_path = "/custom/path/names.json"
+end
+```
+
+## Account Names Setup
+
+### File Format
+
+`account_names.json` is a simple JSON object mapping friendly names to 8-digit account numbers:
+
+```json
+{
+  "descriptive_name": "account_number"
+}
+```
+
+## Using Account Names
+
+### Methods Supporting Account Names
+
+All account-specific methods support both `account_hash` and `account_name`:
+
+- `get_account(account_name:)` or `get_account(account_hash)`
+- `get_order(order_id, account_name:)`
+- `cancel_order(order_id, account_name:)`
+- `get_account_orders(account_name:)`
+- `place_order(order_spec, account_name:)`
+- `replace_order(order_id, order_spec, account_name:)`
+- `preview_order(order_spec, account_name:)`
+- `get_transactions(account_name:)`
+- `get_transaction(activity_id, account_name:)`
+
+### Calling Patterns
+
+```ruby
+# Using account name (keyword argument) - RECOMMENDED
+client.get_account(account_name: "my_trading_account")
+
+# Using account hash (positional argument) - still works
+client.get_account("ABC123HASH")
+
+# Using account hash (keyword argument)
+client.get_account(account_hash: "ABC123HASH")
+
+# Priority: account_name always takes precedence
+client.get_account("HASH1", account_name: "my_ira")  # Uses "my_ira"
+```
+
+### List Available Accounts
+
+```ruby
+# Get list of configured account names
+names = client.available_account_names
+# => ["my_trading_account", "my_ira", "my_roth_ira"]
+
+puts "Available accounts:"
+names.each { |name| puts "  - #{name}" }
+```
+
+## Security
+
+### 1. Protect Your Files
+
+The account files contain sensitive information:
+
+```bash
+# Set restrictive permissions
+chmod 600 ~/.schwab_rb/account_names.json
+chmod 600 ~/.schwab_rb/account_hashes.json
+
+# Verify permissions
+ls -l ~/.schwab_rb/
+```
+
+### 2. Don't Commit to Version Control
+
+Add to `.gitignore`:
+
+```
+.schwab_rb/
+**/account_names.json
+**/account_hashes.json
+```
+
+### 3. Environment-Specific Configs
+
+Use different configs per environment:
+
+```ruby
+# In development
+SchwabRb.configure do |config|
+  config.schwab_home = "~/.schwab_rb/development"
+end
+
+# In production
+SchwabRb.configure do |config|
+  config.schwab_home = ENV['SCHWAB_CONFIG_PATH']
+end
+```
+
+## Troubleshooting
+
+### Account Name Not Found
+
+**Error**: `Account name 'my_account' not found in account hashes.`
+
+**Solutions**:
+1. Run `client.get_account_numbers` to populate hashes
+2. Check spelling in `account_names.json`
+3. Verify account number is correct
+
+### Account Numbers File Missing
+
+**Error**: `Account names file not found at ~/.schwab_rb/account_names.json`
+
+**Solutions**:
+1. Create the file with your account mappings (see [Quick Start](#quick-start))
+2. Set custom path via config if file is elsewhere
+
+### Account Not in API Response
+
+**Warning**: `Account 'old_account' (98765432) not found in API response.`
+
+This warning means an account in your `account_names.json` wasn't returned by the API.
+
+**Possible Causes**:
+- Account was closed
+- Wrong account number in `account_names.json`
+- Account not accessible with current API credentials
+
+**Actions**:
+1. Verify account status on Schwab website
+2. Check account number in `account_names.json`
+3. Remove closed accounts from config
+
+### Stale Account Hashes
+
+The gem automatically handles stale hashes:
+1. Request fails with stale hash
+2. Calls `get_account_numbers` to refresh
+3. Retries request with new hash
+4. If still fails, raises original error
+
+## API Reference
+
+### Client Methods
+
+#### `available_account_names`
+
+Returns list of configured account names.
+
+```ruby
+client.available_account_names
+# => ["my_trading_account", "my_ira"]
+```
+
+**Returns**: `Array<String>` - List of account names from `account_names.json`
+**Returns**: `[]` - Empty array if file doesn't exist
+
+#### Account-Specific Methods
+
+All methods accept either `account_name:` or `account_hash`:
+
+```ruby
+# Get account
+client.get_account(account_name: "my_trading_account")
+client.get_account("ABC123HASH")
+
+# Get orders
+client.get_account_orders(account_name: "my_ira", max_results: 10)
+
+# Place order
+client.place_order(order_spec, account_name: "my_trading_account")
+```
+
+### AccountHashManager
+
+Direct access to the account hash manager:
+
+```ruby
+manager = SchwabRb::AccountHashManager.new
+
+# Get available names
+manager.available_account_names
+# => ["my_trading_account", "my_ira"]
+
+# Get hash by name
+manager.get_hash_by_name("my_trading_account")
+# => "ABC123HASH"
+
+# Get all hashes
+manager.get_all_hashes
+# => {"my_trading_account" => "ABC123HASH", "my_ira" => "XYZ789HASH"}
+```
+
+---
+
+For more information, see the [main README](../README.md) or visit [github.com/jwplatta/schwab_rb](https://github.com/jwplatta/schwab_rb).

data/doc/PLACE_ORDER_SAMPLES.md

@@ -0,0 +1,301 @@
+# Place Order Samples
+
+Below, you will find examples specific to orders for use in the Schwab Trader API POST and PUT Order endpoints. Order entry will only be available for the assetType 'EQUIT' and 'OPTION as of this time.
+
+Trader API applications (Individual and Commercial) are limited in the number of PUT/POST/DELETE order requests per minute per account based on the properties of the application specified during registration or follow-up process. Throttle limits for orders can be set from zero (0) to 120 requests per minute per account. Get order requests are unthrottled. Contact TraderAPI@schwab.com for further information.
+
+Options and their Symbology:
+Options symbols are broken down as:
+Underlying Symbol (6 characters including spaces) | Expiration (6 characters) | Call/Put (1 character) | Strike Price (5+3=8 characters)
+
+```
+Option Symbol: XYZ 210115C00050000
+Stock Symbol: XYZ
+Expiration: 2021/01/15
+Type: Call
+Strike Price: $50.00
+
+Option Symbol: XYZ 210115C00055000
+Stock Symbol: XYZ
+Expiration: 2021/01/15
+Type: Call
+Strike Price: $55.00
+
+Option Symbol: XYZ 210115C00062500
+Stock Symbol: XYZ
+Expiration: 2021/01/15
+Type: Call
+Strike Price: $62.50
+```
+
+Instruction for EQUITY and OPTION
+
+Instruction	EQUITY (Stocks and ETFs)	Option
+BUY	ACCEPTED	REJECT
+SELL	ACCEPTED	REJECT
+BUY_TO_OPEN	REJECT	ACCEPTED
+BUY_TO_COVER	ACCEPTED	REJECT
+BUY_TO_CLOSE	REJECT	ACCEPTED
+SELL_TO_OPEN	REJECT	ACCEPTED
+SELL_SHORT	ACCEPTED	REJECT
+SELL_TO_CLOSE	REJECT	ACCEPTED
+Buy Market: Stock
+Buy 15 shares of XYZ at the Market good for the Day.
+
+```json
+{
+  "orderType": "MARKET",
+  "session": "NORMAL",
+  "duration": "DAY",
+  "orderStrategyType": "SINGLE",
+  "orderLegCollection": [
+   {
+    "instruction": "BUY",
+    "quantity": 15,
+    "instrument": {
+     "symbol": "XYZ",
+     "assetType": "EQUITY"
+    }
+   }
+  ]
+}
+```
+
+## Buy Limit: Single Option
+
+Buy to open 10 contracts of the XYZ March 15, 2024 $50 CALL at a Limit of $6.45 good for the Day.
+
+```json
+{
+  "complexOrderStrategyType": "NONE",
+  "orderType": "LIMIT",
+  "session": "NORMAL",
+  "price": "6.45",
+  "duration": "DAY",
+  "orderStrategyType": "SINGLE",
+  "orderLegCollection": [
+   {
+    "instruction": "BUY_TO_OPEN",
+    "quantity": 10,
+    "instrument": {
+     "symbol": "XYZ   240315C00500000",
+     "assetType": "OPTION"
+    }
+   }
+  ]
+}
+```
+
+## Buy Limit: Vertical Call Spread
+Buy to open 2 contracts of the XYZ March 15, 2024 $45 Put and Sell to open 2 contract of the XYZ March 15, 2024 $43 Put at a LIMIT price of $0.10 good for the Day.
+
+```json
+{
+  "orderType": "NET_DEBIT",
+  "session": "NORMAL",
+  "price": "0.10",
+  "duration": "DAY",
+  "orderStrategyType": "SINGLE",
+  "orderLegCollection": [
+   {
+    "instruction": "BUY_TO_OPEN",
+    "quantity": 2,
+    "instrument": {
+     "symbol": "XYZ   240315P00045000",
+     "assetType": "OPTION"
+    }
+   },
+   {
+    "instruction": "SELL_TO_OPEN",
+    "quantity": 2,
+    "instrument": {
+     "symbol": "XYZ   240315P00043000",
+      "assetType": "OPTION"
+    }
+   }
+  ]
+}
+```
+
+## Conditional Order: One Triggers Another
+Buy 10 shares of XYZ at a Limit price of $34.97 good for the Day. If filled, immediately submit an order to Sell 10 shares of XYZ with a Limit price of $42.03 good for the Day. Also known as 1st Trigger Sequence.
+
+```json
+{
+  "orderType": "LIMIT",
+  "session": "NORMAL",
+  "price": "34.97",
+  "duration": "DAY",
+  "orderStrategyType": "TRIGGER",
+  "orderLegCollection": [
+   {
+    "instruction": "BUY",
+    "quantity": 10,
+    "instrument": {
+     "symbol": "XYZ",
+     "assetType": "EQUITY"
+    }
+   }
+  ],
+  "childOrderStrategies": [
+   {
+    "orderType": "LIMIT",
+    "session": "NORMAL",
+    "price": "42.03",
+    "duration": "DAY",
+    "orderStrategyType": "SINGLE",
+    "orderLegCollection": [
+     {
+      "instruction": "SELL",
+      "quantity": 10,
+      "instrument": {
+       "symbol": "XYZ",
+       "assetType": "EQUITY"
+      }
+     }
+    ]
+   }
+  ]
+}
+```
+
+
+## Conditional Order: One Cancels Another
+
+  Sell 2 shares of XYZ at a Limit price of $45.97 and Sell 2 shares of XYZ with a Stop Limit order where the stop price is $37.03 and limit is $37.00. Both orders are sent at the same time. If one order fills, the other order is immediately cancelled. Both orders are good for the Day. Also known as an OCO order.
+
+```json
+{
+  "orderStrategyType": "OCO",
+  "childOrderStrategies": [
+   {
+    "orderType": "LIMIT",
+    "session": "NORMAL",
+    "price": "45.97",
+    "duration": "DAY",
+    "orderStrategyType": "SINGLE",
+    "orderLegCollection": [
+     {
+      "instruction": "SELL",
+      "quantity": 2,
+      "instrument": {
+       "symbol": "XYZ",
+       "assetType": "EQUITY"
+      }
+     }
+    ]
+   },
+   {
+    "orderType": "STOP_LIMIT",
+    "session": "NORMAL",
+    "price": "37.00",
+    "stopPrice": "37.03",
+    "duration": "DAY",
+    "orderStrategyType": "SINGLE",
+    "orderLegCollection": [
+     {
+      "instruction": "SELL",
+      "quantity": 2,
+      "instrument": {
+       "symbol": "XYZ",
+       "assetType": "EQUITY"
+      }
+     }
+    ]
+   }
+  ]
+}
+```
+
+
+## Conditional Order: One Triggers A One Cancels Another
+
+Buy 5 shares of XYZ at a Limit price of $14.97 good for the Day. Once filled, 2 sell orders are immediately sent: Sell 5 shares of XYZ at a Limit price of $15.27 and Sell 5 shares of XYZ with a Stop order where the stop price is $11.27. If one of the sell orders fill, the other order is immediately cancelled. Both Sell orders are Good till Cancel. Also known as a 1st Trigger OCO order.
+
+```json
+{
+  "orderStrategyType": "TRIGGER",
+  "session": "NORMAL",
+  "duration": "DAY",
+  "orderType": "LIMIT",
+  "price": 14.97,
+  "orderLegCollection": [
+   {
+    "instruction": "BUY",
+    "quantity": 5,
+    "instrument": {
+     "assetType": "EQUITY",
+     "symbol": "XYZ"
+    }
+   }
+  ],
+  "childOrderStrategies": [
+   {
+    "orderStrategyType": "OCO",
+    "childOrderStrategies": [
+     {
+      "orderStrategyType": "SINGLE",
+      "session": "NORMAL",
+      "duration": "GOOD_TILL_CANCEL",
+      "orderType": "LIMIT",
+      "price": 15.27,
+      "orderLegCollection": [
+       {
+        "instruction": "SELL",
+        "quantity": 5,
+        "instrument": {
+         "assetType": "EQUITY",
+         "symbol": "XYZ"
+        }
+       }
+      ]
+     },
+     {
+      "orderStrategyType": "SINGLE",
+      "session": "NORMAL",
+      "duration": "GOOD_TILL_CANCEL",
+      "orderType": "STOP",
+      "stopPrice": 11.27,
+      "orderLegCollection": [
+       {
+        "instruction": "SELL",
+        "quantity": 5,
+        "instrument": {
+         "assetType": "EQUITY",
+         "symbol": "XYZ"
+        }
+       }
+      ]
+     }
+    ]
+   }
+  ]
+}
+```
+
+## Sell Trailing Stop: Stock
+
+Sell 10 shares of XYZ with a Trailing Stop where the trail is a -$10 offset from the time the order is submitted. As the stock price goes up, the -$10 trailing offset will follow. If stock XYZ goes from $110 to $130, your trail will automatically be adjusted to $120. If XYZ falls to $120 or below, a Market order is submitted. This order is good for the Day.
+
+```json
+{
+  "complexOrderStrategyType": "NONE",
+  "orderType": "TRAILING_STOP",
+  "session": "NORMAL",
+  "stopPriceLinkBasis": "BID",
+  "stopPriceLinkType": "VALUE",
+  "stopPriceOffset": 10,
+  "duration": "DAY",
+  "orderStrategyType": "SINGLE",
+  "orderLegCollection": [
+   {
+    "instruction": "SELL",
+    "quantity": 10,
+    "instrument": {
+     "symbol": "XYZ",
+     "assetType": "EQUITY"
+    }
+   }
+  ]
+}
+```