diff --git a/guides/bridge-examples.md b/guides/bridge-examples.md index 93669e0..56646a0 100644 --- a/guides/bridge-examples.md +++ b/guides/bridge-examples.md @@ -15,6 +15,7 @@ families are grouped by external protocol or adapter contract, not by transport. | BotBinary/BinaryBot | `optionx_cpp/bridges/bot_binary.hpp` | `BotBinaryBridgeConfig` | `examples/bot_binary_bridge_smoke.cpp` | Compatibility intake for BotBinary `request=...` HTTP URLs and file-signal filenames. | | BotBinary command helper | `optionx_cpp/bridges/bot_binary.hpp` | none | `examples/bot_binary_command_builder_smoke.cpp` | Formatter/parser helper for legacy BotBinary command strings. | | Legacy trading pipe | `optionx_cpp/bridges/legacy_trading.hpp` | `LegacyTradingBridgeConfig` | `examples/named_pipe_bridge_smoke.cpp` | Compatibility bridge for the older named-pipe JSON trading protocol. | +| Telegram signal bridge | `optionx_cpp/bridges/telegram.hpp` | `TelegramSignalBridgeConfig` | `examples/telegram_signal_bridge_smoke.cpp` | Deterministic parser, source boundary, signal callback, duplicate report, and shutdown lifecycle without Telegram credentials. | ## Choosing A Bridge @@ -29,6 +30,10 @@ families are grouped by external protocol or adapter contract, not by transport. BotBinary command string or file-signal filename. - Use the legacy trading pipe only for old clients that already speak that named-pipe JSON format. +- Use the Telegram signal bridge when a user-client source must turn channel + messages into normalized signals. The production source is expected to be a + `tg-client-stdio` adapter; the parser and bridge can be tested independently + with a fake source. Compatibility bridges should convert their external payload into `TradeSignal` callbacks and reports. They do not need to expose Bridge Protocol v1 endpoints diff --git a/guides/bridge-taxonomy.md b/guides/bridge-taxonomy.md index b1369f7..546e15e 100644 --- a/guides/bridge-taxonomy.md +++ b/guides/bridge-taxonomy.md @@ -28,11 +28,18 @@ OptionX protocol together. | TradingView extension | `optionx_cpp/bridges/trading_view.hpp` | Adapter for payloads emitted by `browser_extensions/tradingview-alert-extension`. | HTTP. | | BinaryBot/BotBinary | `optionx_cpp/bridges/bot_binary.hpp` | Compatibility bridge and formatter/parser helpers for observed BinaryBot-compatible command strings. | HTTP `request=...`, file-signal name. | | Legacy trading pipe | `optionx_cpp/bridges/legacy_trading.hpp` | Compatibility bridge for the older named-pipe JSON trading protocol. | Named pipe. | +| Telegram signal bridge | `optionx_cpp/bridges/telegram.hpp` | User-client message parser and live signal adapter. The Telegram worker/session remains an external source boundary. | stdio worker source, with source adapters kept outside the parser. | All families converge internally on OptionX DTOs such as `TradeSignal`, `TradeRequest`, account snapshots and bridge callbacks. The public wire format does not need to be the same for every family. +Telegram is a source adapter family rather than a transport-only family. The +public bridge consumes `TelegramMessageSource` callbacks, while authorization, +proxy handling, dialog discovery and historical export belong to the +`tg-client-stdio` worker/supervisor layer. Historical export remains a separate +archive capability and is not added to `BaseBridge`. + For practical embedding of the native HTTP/WebSocket server bridge, see `guides/protocol-v1-bridge-runtime.md`. For runnable bridge entry points, see `examples/README.md`. diff --git a/guides/telegram-bridge-design.md b/guides/telegram-bridge-design.md index c4d97c2..3886050 100644 --- a/guides/telegram-bridge-design.md +++ b/guides/telegram-bridge-design.md @@ -1,7 +1,8 @@ # Telegram Bridge Design -This document captures the intended direction for a future Telegram signal -bridge. It is a design note, not a committed public API. +This document captures the architecture and current boundaries of the Telegram +signal bridge. The public C++ DTO/parser/bridge layer is implemented, while +the authorized Telegram worker adapter remains a separate integration step. ## Problem Shape @@ -53,6 +54,12 @@ newline-delimited JSON over stdin/stdout. Keep the protocol versioned so a framed transport can replace JSONL later if media bytes ever need to cross the stdio boundary. +The current OptionX bridge does not own a Telethon process. It consumes the +`TelegramMessageSource` interface, so fake sources can exercise parsing and +lifecycle without credentials. The concrete source adapter will bind that +interface to `tg-client-stdio::WorkerClient` after the worker repository's +supervisor and typed archive API are merged and pinned by OptionX. + ## Stdio Protocol Envelope Every JSONL record should use an envelope so responses, long-running exports, @@ -107,7 +114,7 @@ Keep the live bridge, archive export, and parsing separate. ### Worker Client -`TelegramWorkerClient` owns the process/session protocol. It should expose +`tg-client-stdio::WorkerClient` owns the process/session protocol. It exposes operations such as: - `auth.status`; @@ -131,6 +138,11 @@ message events into `TradeSignal` callbacks and signal reports. It should not expose historical export through `BaseBridge::run()` or `process()`. Bridge lifecycle remains live-intake lifecycle. +The current bridge also applies a bounded identity-based dedupe cache. Parser +diagnostics, duplicate messages, allocator failures and callback failures are +reported through `BridgeSignalReport`; they do not silently become accepted +signals. + ### Archive Source Historical export is a separate capability. The first implementation can be @@ -308,17 +320,26 @@ Proxy config should support at least SOCKS5 and HTTP where the underlying Telegram client library supports them. Proxy failures must be distinct from authorization failures. -## First PR Sequence +## Implementation Status And Next Steps + +Completed without an authorized Telegram session: + +1. `tg-client-stdio` worker protocol for dialogs, streaming export, + live listen/stop, auth status/code/2FA and HTTP/SOCKS proxy configuration. +2. C++ worker supervisor and typed raw-message export DTOs in the standalone + worker repository. +3. OptionX raw/parsed Telegram DTOs, deterministic regex parser and + source-independent `TelegramSignalBridge`. +4. Fake-source unit coverage and a runnable no-credentials bridge example. + +Next steps: -1. Refactor `telegram-monitoring-tool` into a non-interactive worker command - with the JSONL envelope above, preserving the current interactive CLI as a - thin wrapper if needed. -2. Add worker operations for `dialogs.list`, `messages.export` and - `messages.listen`. -3. Add C++ protocol DTOs and a small worker client/supervisor in OptionX. -4. Add `TelegramSignalParser` with pure text fixture tests. -5. Add `TelegramSignalBridge` live intake using the parser. -6. Add archive/parser example for historical backtest fixture generation. +1. Merge and pin the worker repository's supervisor/archive PRs. +2. Add `TelegramMessageSource` adapter code around `WorkerClient` and test it + against the mock worker process. +3. Add a historical archive/parser fixture example. +4. Perform the first real authorization, proxy and live-channel check with an + operator-provided Telegram session. -Keep the first OptionX PR focused on DTOs, parser and docs if the worker is not -ready yet. +OCR/vision remains a separate optional provider and should not block the text +parser or the first authorized-session test.