feat: add @traderalice/ibkr TWS API package + refactors#59
Merged
luokerenx4 merged 11 commits intomasterfrom Mar 15, 2026
Merged
feat: add @traderalice/ibkr TWS API package + refactors#59luokerenx4 merged 11 commits intomasterfrom
luokerenx4 merged 11 commits intomasterfrom
Conversation
Vendor the official IBJts distribution from interactivebrokers.github.io into packages/ibkr/ref/ as translation reference for the TypeScript port. Included: - source/proto/ — 203 .proto files (protocol source of truth) - source/pythonclient/ — Python client (translation target) - samples/Python/ — usage examples Java/C++ clients excluded from git (available locally, in .gitignore). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…wrapper TypeScript port of IBKR TWS API v10.44.01, translated from official Python client. Package structure mirrors ibapi/ for cross-reference. Completed layers: - Constants & sentinel values (const, errors, server-versions, message) - All data models (contract, order, execution, scanner, common, etc.) - Protocol layer (comm, connection, reader, utils) - Decoder (message dispatch + all processXxxMsg handlers) - OrderDecoder (version-gated order field extraction) - EWrapper interface + DefaultEWrapper (143 callback methods) Still needed: EClient (request encoding — the largest file at 7500 lines in Python). Protobuf bindings auto-generated via generate-proto.sh but excluded from git (in .gitignore). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Split client.py (7500 lines Python) into modular TypeScript files: - client/base.ts — EClient class, connect/disconnect, handshake, sendMsg - client/encode.ts — shared contract field encoding helpers - client/market-data.ts — reqMktData, reqTickByTick, exerciseOptions, etc. - client/orders.ts — placeOrder (1000+ line beast), cancelOrder, reqOpenOrders - client/account.ts — reqAccountSummary, reqPositions, reqContractDetails, etc. - client/historical.ts — reqHistoricalData, reqScanner, reqNews, verify, etc. - client/index.ts — assembles mixins onto EClient.prototype Text protocol only for now (protobuf paths marked TODO). All 34 source files (9527 lines) pass type-check with zero errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
TWS v222 sends ALL responses as protobuf (msgId + 200 offset). Fixed onMessage() to match Python's run() loop: - v201+: read 4-byte binary msgId, if > 200 → protobuf, else → text - Legacy: text msgId as first \0-delimited field Also fixed decoder.interpret() to accept msgId parameter (matching Python's signature) and added processProtoBuf() stub for protobuf messages. Verified: handshake succeeds, protobuf messages correctly identified (currentTime=49, nextValidId=9, error=4, managedAccounts=15). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Ported from official ibapi tests: - comm.test.ts — encode/decode round-trips (from test_comm.py) - account-summary-tags.test.ts (from test_account_summary_tags.py) - order-condition.test.ts — condition construction + encode/decode - utils.test.ts — decode functions + formatting helpers Added beyond Python coverage: - models.test.ts — data model construction and defaults - Additional comm tests (binary protocol, protobuf framing, edge cases) - Decode function tests (sentinel values, Infinity, UNSET handling) All 51 tests pass. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
TDD: wrote failing tests first, then implemented processProtoBuf handlers. Protobuf handlers implemented: - CurrentTime (IN.49) — reqCurrentTime response - NextValidId (IN.9) — auto-sent on connect - ErrorMessage (IN.4) — error/info notifications - ManagedAccounts (IN.15) — account list on connect - CurrentTimeInMillis (IN.109) — millisecond timestamp Verified against live TWS v222: - Handshake → protobuf dispatch → wrapper callbacks all working - currentTime, nextValidId, managedAccounts decoded correctly - 56 tests pass (51 existing + 5 new protobuf) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… support Replaced monolithic decoder.ts (2018 lines) with decoder/ directory: - decoder/base.ts (90 lines) — Decoder class skeleton + dispatch - decoder/market-data.ts (469) — tick, depth, reroute handlers - decoder/orders.ts (789) — order status, open/completed order handlers - decoder/account.ts (487) — account, position, PnL handlers - decoder/contract.ts (682) — contract data, bond, symbol samples handlers - decoder/execution.ts (263) — execution, commission report handlers - decoder/historical.ts (586) — historical data, realtime bars, tick-by-tick - decoder/misc.ts (833) — news, scanner, verify, WSH, config handlers - decoder/index.ts — assembles all handler groups Each file contains BOTH text protocol AND protobuf handlers for its message category. All 83 protobuf handlers from Python's decoder.py are now implemented. Also: moved test-connect.ts → tests/connect.integration.ts 56 tests pass. Live TWS v222 connection verified. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Renamed *.test.ts → *.spec.ts to match main project convention.
Renamed *.integration.ts → *.e2e.ts for integration tests.
Added vitest configs:
- vitest.config.ts — unit tests (*.spec.ts), run via `pnpm test`
- vitest.e2e.config.ts — integration tests (*.e2e.ts), run via `pnpm test:e2e`
Requires running TWS/IB Gateway. 15s timeout.
Added contract-details.e2e.ts — reqContractDetails("AAPL") round-trip test.
Verified: conId=265598, longName=APPLE INC, primaryExchange=NASDAQ.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- tests/e2e/setup.ts — shared connection, wrapper, results collector
- tests/e2e/*.e2e.spec.ts — import { client, results } from setup
- Shared connection eliminates clientId conflicts between test files
- waitFor() helper for async result polling
Test commands:
- pnpm test — unit tests only (CI safe, 56 tests)
- pnpm test:e2e — integration tests (needs TWS, 9 tests)
- pnpm test:all — both
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Quick start, architecture overview, project structure explanation, testing guide, protobuf generation instructions, and relationship to official IBKR API. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Captures the full journey: evaluating connection options (@stoqey/ib vs Client Portal REST vs self-built), understanding the official distribution, dual protocol discovery, translation strategy decisions, why files are split by category, key Python→TypeScript adaptations, testing strategy, and what's not yet implemented. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@traderalice/ibkrpackage: Pure TypeScript port of the IBKR TWS API — types, protocol layer, protobuf decoder, EClient with all 100+ request methods, and comprehensive test suite (51 tests)GenerateProvider→AIProvider, push history serialization into providers, removeinputKind, consolidate provider utilsTest plan
pnpm test)pnpm build+pnpm start🤖 Generated with Claude Code