t-tech-investments 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cff97b258ff7384f55f88ee890266d106003ba1e61ccaf0f140db45b6f981f55
-  data.tar.gz: 3d03d9e98cedc667ef2462e6aaba1824c5dc54b85fd34601241ba6aae90c911a
+  metadata.gz: 2e68074e95141d63fe02be0f024fdba50ec74b935b61f95cdc35754dd368484f
+  data.tar.gz: adcdccd09aed1a6bcc83e274f7c02cf954a5f05645740aad949027af7fe8352d
 SHA512:
-  metadata.gz: 49373e6e1b2b729b41701a778f2b1f2e7d9ab302b2231aaaa9d9cacb30816a8eba8784ca428f1ddce8abea1cd27d5e980df38fbd29f157ced37fafe135236a39
-  data.tar.gz: a0bb1a988d286d8bfe2117c1b482b36a29bda4b090c355cdbe9acc98dd1aa663d38384c17af4a77ce07b21df262cea51c2c26daccea37963f5f8f8ea70a6fdc5
+  metadata.gz: 83bb6a2f390c88557029f0b349670f393faed7da128e368bec3829154490ee9921e0af9c7532278ddd34b72f800444408380ce373bdfb57827f253cb11871fb3
+  data.tar.gz: 832db0d5502ac1d24562d9703ada3f224248778857bc551e261a88351620f8977cbb16c6e95d5b1279349209cc827cf5500f5e8edf162a241d1c32ce84aaf89d

data/.cursor/rules/git-flow.mdc

@@ -1,12 +1,56 @@
 ---
-description: Git Flow: ветки и слияния
+description: >
+  Правила следования Git Flow для разработки торговой системы.
+  Определяет модель веток, правила коммитов и merge-стратегии.
+
+globs:
+  - "**/*"
+
 alwaysApply: true
 ---
+В проекте используется Git Flow.
+
+Основные ветки:
+- main — стабильная ветка, всегда в рабочем состоянии.
+- develop — основная ветка разработки.
+
+Рабочие ветки:
+- feature/* — разработка новых фич и модулей
+- bugfix/* — исправления ошибок
+- hotfix/* — срочные исправления для main
+- release/* — подготовка релиза
+
+Правила работы:
+- Прямая разработка в main запрещена.
+- Новые фичи всегда начинаются от develop.
+- Feature-ветки мержатся обратно только в develop.
+- Hotfix-ветки начинаются от main и мержатся в main и develop.
+- Release-ветки используются для стабилизации перед релизом.
+
+Коммиты:
+- Коммиты атомарные и логически завершённые.
+- Один коммит — одно логическое изменение.
+- Сообщения коммитов описывают ЧТО и ЗАЧЕМ, а не КАК.
 
-# Git Flow
+Рекомендованный формат commit message:
+- feat: добавление новой функциональности
+- fix: исправление ошибки
+- refactor: рефакторинг без изменения поведения
+- chore: инфраструктурные изменения
+- test: добавление или изменение тестов
+- docs: документация
 
-**Ветки:** main — только прод (через release/hotfix). develop — интеграция, от неё feature.
+Примеры:
+- feat(strategy): add breakout strategy
+- fix(risk): prevent position size overflow
+- refactor(execution): simplify order state machine
 
-**Именование:** `feature/имя` ← develop → develop; `release/1.2.0` ← develop → main + develop; `hotfix/имя` ← main → main + develop.
+Merge:
+- Предпочтителен merge commit или squash (осознанно).
+- Избегать rebase на общих ветках (develop, main).
+- Конфликты решаются до merge, не после.
 
-Предлагать эти шаблоны веток, feature сливать в develop, не в main.
+Cursor должен:
+- учитывать текущую ветку при генерации изменений
+- не предлагать изменения напрямую в main
+- придерживаться Git Flow при создании новых задач и файлов

data/.cursor/rules/sdk-architecture.mdc

@@ -0,0 +1,30 @@
+---
+description: Минимальная архитектура SDK: слои, зависимости, контракты
+alwaysApply: true
+---
+
+# Архитектура SDK (минимум правил)
+
+## Слои
+
+- `Client` (facade) → `Services` (adapters) → `Transport` (gRPC)
+- Вспомогательные: `Coercers/Mappers`, `Errors`, `Proto` (сгенерёнка)
+
+## Зависимости (жёсткие запреты)
+
+- `Services` не вызывают gRPC stub напрямую — только через `Transport`.
+- Публичный API не возвращает protobuf по умолчанию (только `raw:`/debug, если нужен).
+- `Transport` без бизнес-логики; только: metadata, deadlines, retries-policy, error mapping.
+- `Coercers/Mappers` — чистые и детерминированные (без IO/сети).
+
+## Контракты (invest-contracts)
+
+- Контракты **пинуем по tag/SHA** (не `master`), храним в `contracts.lock`.
+- Сгенерированный Ruby protobuf/gRPC код **коммитим** в `lib/**/proto/**` (установка гема без `protoc`).
+- Обновление контрактов обязано включать: pin → реген → тест “все RPC экспонированы”.
+
+## T‑Invest инварианты (transport обязан)
+
+- metadata каждого запроса: `Authorization: Bearer <token>`; `x-app-name` (если задан).
+- endpoints по умолчанию (конфигурируемо): prod/sandbox.
+- `x-tracking-id`: извлекать из unary headers и прокидывать в ошибки/логи; для stream — логировать tracking id из статусных сообщений подписки.

data/.cursor/rules/sdk-code-standards.mdc

@@ -0,0 +1,22 @@
+---
+description: Минимальные стандарты кода/PR для SDK
+alwaysApply: true
+---
+
+# Код и процесс (минимум правил)
+
+## Стиль/качество
+
+- Ruby **>= 3.2**, стиль — через `rubocop` (double quotes и т.д.).
+- `rubocop` и `rspec` обязаны проходить.
+- Не логировать секреты (token/credentials).
+- Protobuf наружу не экспонировать по умолчанию (только `raw:`/debug).
+
+## Контракты
+
+- Любое обновление `invest-contracts` включает: обновить pin tag/SHA → реген `lib/**/proto/**` → golden test “все RPC экспонированы”.
+
+## Git/PR
+
+- Следовать git-flow из `.cursor/rules/git-flow.mdc` (feature от `develop` → `develop`).
+- PR: кратко “что/зачем” + тест-план + breaking/non-breaking для публичного Ruby API.

data/.cursor/rules/sdk-patterns.mdc

@@ -0,0 +1,22 @@
+---
+description: Минимальные паттерны: auto-expose RPC, coercion, streaming API
+alwaysApply: true
+---
+
+# Паттерны (минимум правил)
+
+## 1) “Все методы реализованы”
+
+- RPC **экспонируются автоматически** из descriptor’ов/Stub’ов (метапрограммирование).
+- Нельзя вручную поддерживать списки методов или дублировать proto-структуру в коде.
+
+## 2) Преобразования Ruby ↔ protobuf
+
+- Вход в unary/stream управление: Ruby hash/kwargs → protobuf message через reflection (descriptor).
+- Выход наружу: protobuf response → Ruby-friendly hash/DTO; protobuf наружу только `raw:`/debug.
+
+## 3) Streaming (block/yield)
+
+- Streaming API наружу: `client.market_data.stream { |s| s.subscribe_*; s.each_event { |event| ... } }`.
+- Внутри: bidi stream + очередь исходящих команд; server ping игнорируется.
+- Для MarketDataStream: reconciliation через `GetMySubscriptions` (рассинхрон → resubscribe; пусто → restart).

data/.cursor/rules/sdk-testing.mdc

@@ -0,0 +1,19 @@
+---
+description: Тесты без сети: golden checks, coercion, streaming через fake transport
+alwaysApply: true
+---
+
+# Тестирование (строго без сети)
+
+- Любые тесты **без сетевых вызовов** (ни prod, ни sandbox).
+- Тестируем только: преобразования, поведение SDK, соответствие контрактам и документации.
+
+## Обязательные проверки
+
+- **Golden test “все RPC экспонированы”**: после регенерации proto тест падает, если появился новый RPC, но SDK его не выставил.
+- **Coercers/Mappers**: reflection-based Hash/kwargs ↔ protobuf (enum/time/money/oneof).
+- **Transport**: `GRPC::BadStatus` → `Errors::*`, извлечение `x-tracking-id` (unary headers), redaction секретов.
+- **Streaming**: тестировать через fake transport + controlled `Enumerator`:
+  - ping игнорируется
+  - статусы подписки (включая `TOO_MANY_REQUESTS`) мапятся в события/ошибки
+  - reconciliation через `GetMySubscriptions` (рассинхрон → resubscribe; пусто → restart)

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.1.1] - 2026-02-05
+
+- Docs: update README with correct links and env options
+
 ## [0.1.0] - 2026-02-05
 
 - Initial release

data/README.md

@@ -1,6 +1,6 @@
 # T::Tech::Investments
 
-Ruby-обёртка над gRPC API [T-Bank Invest API](https://opensource.tbank.ru/invest/invest-contracts). Контракты (proto-файлы) берутся из репозитория [invest-contracts](https://opensource.tbank.ru/invest/invest-contracts/-/tree/master/src/docs/contracts); гем даёт удобный Ruby-клиент для работы с брокерским счётом, инструментами, заявками и стримами маркет-данных.
+Ruby-обёртка над gRPC API [T-Bank Invest API](https://developer.tbank.ru/invest/intro/intro/). Контракты (proto-файлы) берутся из репозитория [investAPI](https://github.com/RussianInvestments/investAPI) и пинятся по SHA в `contracts.lock`; сгенерированный protobuf/gRPC код коммитится в `lib/**/proto/**`. Гем даёт удобный Ruby-клиент для работы с брокерским счётом, инструментами, заявками и стримами маркет-данных.
 
 Гем предназначен для интеграции инвестиционных сервисов T-Bank в Ruby-приложения: типизированные вызовы вместо ручной работы с gRPC, единый стиль API и опора на официальные контракты.
 
@@ -18,9 +18,200 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install t-tech-investments
 ```
 
+## Minimal requirements (Prod / Sandbox)
+
+Минимум, который нужен пользователю, чтобы начать работать с T-Invest API:
+
+- **Ruby**: >= 3.2
+- **Токен доступа**: получите токен в личном кабинете T-Bank Dev Portal (см. “Начало работы”) — [документация](https://developer.tbank.ru/invest/intro/intro/)
+- **Выбор контура**: используйте токен **для прода** или **для песочницы** (sandbox)
+- **gRPC endpoint** (из документации):
+  - **Prod**: `invest-public-api.tbank.ru:443`
+  - **Sandbox**: `sandbox-invest-public-api.tbank.ru:443`
+
+Рекомендуемая форма конфигурации через переменные окружения (названия переменных — соглашение этого гема):
+
+```bash
+# Prod
+export TINVEST_TOKEN="..."
+export TINVEST_ENDPOINT="invest-public-api.tbank.ru:443"
+
+# или Sandbox
+export TINVEST_TOKEN="..."
+export TINVEST_ENDPOINT="sandbox-invest-public-api.tbank.ru:443"
+```
+
+Опционально (ENV-first конфигурация):
+
+```bash
+# Идентификатор приложения (x-app-name)
+export TINVEST_APP_NAME="my-app"
+
+# Таймаут по умолчанию (секунды)
+export TINVEST_TIMEOUT="10"
+
+# Путь к PEM с CA-сертификатами (для кастомных окружений)
+export TINVEST_SSL_CA_CERTS="/path/to/ca.pem"
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+Гем предлагает “глобальную” конфигурацию по умолчанию + возможность переопределить параметры при создании клиента.
+
+### Configuration
+
+#### ENV-first (быстрый старт)
+
+**Given** у вас есть токен и выбран контур (prod/sandbox)  
+**When** вы задаёте `TINVEST_TOKEN` и `TINVEST_ENDPOINT`  
+**Then** вы можете создать клиента без дополнительной настройки
+
+```ruby
+require "t/tech/investments"
+
+client = T::Tech::Investments.client
+```
+
+#### Явная конфигурация (Rails / monolith)
+
+**Given** вы хотите централизованную настройку  
+**When** вы вызываете `T::Tech::Investments.configure`  
+**Then** новые клиенты используют эти значения по умолчанию
+
+```ruby
+T::Tech::Investments.configure do |c|
+  c.token    = ENV.fetch("TINVEST_TOKEN")
+  c.endpoint = ENV.fetch("TINVEST_ENDPOINT", "invest-public-api.tbank.ru:443") # или sandbox
+  c.timeout  = 10
+
+  # опционально
+  c.app_name = "my-app"
+  c.logger   = Logger.new($stdout)
+end
+
+client = T::Tech::Investments.client
+```
+
+#### Override для одного клиента
+
+**Given** вам нужно изменить настройки только для одного вызова/процесса  
+**When** вы передаёте параметры в `client(...)`  
+**Then** они применяются только к этому экземпляру клиента
+
+```ruby
+client = T::Tech::Investments.client(
+  endpoint: "sandbox-invest-public-api.tbank.ru:443",
+  timeout: 2
+)
+```
+
+### Configuration best practices
+
+- **Валидируйте токен**: если токена нет/он пустой — поднимайте `ConfigurationError` (или аналог) с понятным сообщением.
+- **Не логируйте секреты**: токен не должен попадать в логи/исключения.
+- **Снимок конфигурации при создании клиента**: созданный клиент не должен “подхватывать” изменения глобального конфига на лету (важно для потоков/фоновых задач).
+- **Prod vs Sandbox**: различайте контуры только endpoint’ом из документации:
+  - **Prod**: `invest-public-api.tbank.ru:443`
+  - **Sandbox**: `sandbox-invest-public-api.tbank.ru:443`
+
+### Unary requests (получение данных)
+
+Унарные запросы в T‑Invest API — это обычные gRPC-вызовы “один запрос → один ответ”.
+
+#### Авторизация и служебные заголовки
+
+По документации T‑Invest API токен нужно передавать в **metadata каждого запроса** в виде заголовка:
+
+- **`authorization: Bearer <token>`**
+
+Дополнительно (рекомендуется для SDK) можно передавать:
+
+- **`x-app-name`** — идентификатор приложения/SDK для статистики (рекомендации в доке)
+
+Источник: [gRPC — Авторизация / AppName / trackingId](https://developer.tbank.ru/invest/intro/developer/protocols/grpc/).
+
+#### Пример (общий паттерн)
+
+**Given** у вас настроены `TINVEST_TOKEN` и `TINVEST_ENDPOINT`  
+**When** вы вызываете унарный метод сервиса  
+**Then** вы получаете Hash (по умолчанию) или сырой protobuf при `raw: true`
+
+```ruby
+client = T::Tech::Investments.client
+
+# Список аккаунтов (Hash с :accounts и т.д.)
+accounts = client.users.get_accounts
+# С параметрами и опциями
+accounts = client.users.get_accounts(status: :open)
+
+# Свечи по инструменту (from/to — Time или Hash)
+candles = client.market_data.get_candles(
+  figi: "BBG004730N88",
+  from: Time.now - 3600,
+  to: Time.now,
+  interval: :candle_interval_1_min
+)
+
+# Сырой protobuf (для отладки)
+raw_response = client.users.get_accounts(raw: true)
+```
+
+#### Таймауты (deadline)
+
+Для gRPC важно задавать deadline/timeout, чтобы запросы не зависали бесконечно. Вызов должен использовать значение `timeout` из конфигурации (или override при создании клиента).
+
+#### tracking id (x-tracking-id)
+
+Документация отмечает, что **`x-tracking-id` добавляется в ответы unary-методов**. Это UUID запроса, который нужно указывать при обращении в техподдержку.
+
+Рекомендуемая практика для гема:
+
+- логировать/пробрасывать `x-tracking-id` при ошибках;
+- (опционально) предоставлять его пользователю через объект-обёртку ответа или через instrumentation hooks.
+
+### Streaming (MarketData)
+
+Bidirectional stream: в блоке задаёте подписки, затем `each_event` отдаёт события. События — Hash с `:type` и `:data`; **ping игнорируется** SDK.
+
+```ruby
+client = T::Tech::Investments.client
+
+client.market_data.stream do |s|
+  # 1) Подписки (subscription_action: :subscribe или :unsubscribe)
+  s.subscribe_candles(
+    subscription_action: :subscribe,
+    instruments: [{ figi: "BBG004730N88", interval: :subscription_interval_one_minute }],
+    waiting_close: true
+  )
+  s.subscribe_order_book(
+    subscription_action: :subscribe,
+    instruments: [{ figi: "BBG004730N88", depth: 10 }]
+  )
+
+  # 2) Чтение событий (event[:type], event[:data])
+  s.each_event do |event|
+    case event[:type]
+    when :candle
+      puts "candle: #{event[:data].inspect}"
+    when :orderbook
+      puts "orderbook: #{event[:data].inspect}"
+    when :subscribe_candles_response, :subscribe_order_book_response
+      # ответы подписки (tracking_id и статусы в event[:data])
+      warn "subscription: #{event[:data].inspect}"
+    when :trading_status, :last_price, :trade
+      # остальные типы по контракту
+    end
+  end
+end
+```
+
+Reconciliation: при рассинхроне подписок вызовите `s.get_my_subscriptions` и при необходимости переподпишитесь или перезапустите стрим.
+
+Примечания:
+
+- Авторизация для стрима — через metadata `Authorization: Bearer <token>` (как и для unary). Подробнее: [gRPC — Авторизация / AppName / trackingId](https://developer.tbank.ru/invest/intro/developer/protocols/grpc/).
+- В одном стриме можно отправить несколько подписок (свечи, стакан, сделки и т.д.) — каждая своим запросом в очередь.
+- Подробнее: [Описание сервиса котировок](https://developer.tbank.ru/invest/services/quotes/head-marketdata/).
 
 ## Development
 
@@ -30,7 +221,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/t-tech-investments. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/t-tech-investments/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/naveroot/t-tech-investments. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/naveroot/t-tech-investments/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -38,4 +229,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the T::Tech::Investments project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/t-tech-investments/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the T::Tech::Investments project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/naveroot/t-tech-investments/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -9,4 +9,8 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+task :regenerate_proto do
+  sh "bundle exec ruby script/regenerate_proto"
+end
+
 task default: %i[spec rubocop]

data/contracts.lock

@@ -0,0 +1,6 @@
+{
+  "repository": "https://github.com/RussianInvestments/investAPI.git",
+  "ref": "3eaf23a25f598fe483c913184acdbd9132bc68d2",
+  "contracts_path": "src/docs/contracts",
+  "description": "invest-contracts pin (Release 1.43). Update ref then run script/regenerate_proto and golden test."
+}

data/lib/t/tech/investments/client.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module T
+  module Tech
+    module Investments
+      # Client facade: config snapshot, transport, and service adapters (users, instruments, etc.).
+      # Services expose unary RPCs via Transport + Coercers; RPCs are defined from proto descriptors.
+      class Client
+        attr_reader :config
+
+        def initialize(config_snapshot)
+          @config = config_snapshot.validate!
+          @transport = nil
+          @services = {}
+        end
+
+        def transport
+          @transport ||= Transport.new(config)
+        end
+
+        def users
+          service(:users)
+        end
+
+        def instruments
+          service(:instruments)
+        end
+
+        def market_data
+          @market_data ||= begin
+            ProtoLoader.load!
+            unary = Services::UnaryAdapter.new(Services::Registry.service_class(:market_data), transport)
+            Services::MarketDataFacade.new(unary, transport)
+          end
+        end
+
+        def operations
+          service(:operations)
+        end
+
+        def orders
+          service(:orders)
+        end
+
+        def sandbox
+          service(:sandbox)
+        end
+
+        def stop_orders
+          service(:stop_orders)
+        end
+
+        def signals
+          service(:signals)
+        end
+
+        private
+
+        def service(name)
+          return market_data if name == :market_data
+
+          @services[name] ||= begin
+            ProtoLoader.load!
+            Services::UnaryAdapter.new(Services::Registry.service_class(name), transport)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/t/tech/investments/coercers.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module T
+  module Tech
+    module Investments
+      # Reflection-based Hash/kwargs <-> protobuf. No IO; deterministic.
+      # rubocop:disable Metrics/ModuleLength, Metrics/ClassLength
+      module Coercers
+        TIMESTAMP_FULL_NAME = "google.protobuf.Timestamp"
+
+        class << self
+          # Builds a protobuf message instance from a Hash. Keys can be symbols or strings.
+          # Coerces: enum (symbol or int), Time -> Timestamp, nested hashes -> messages, repeated -> array.
+          #
+          # @param message_class [Class] Generated protobuf message class (e.g. GetAccountsRequest)
+          # @param hash [Hash] Attributes (symbol or string keys)
+          # @return [Object] Instance of message_class
+          def to_request(message_class, hash)
+            return message_class.new if hash.nil? || hash.empty?
+
+            msg = message_class.new
+            descriptor = message_class.descriptor
+            pool = ::Google::Protobuf::DescriptorPool.generated_pool
+
+            descriptor.entries.each do |field|
+              value = fetch_value(hash, field.name)
+              next if value.nil?
+
+              set_field(msg, field, value, pool)
+            end
+
+            msg
+          end
+
+          # Converts a protobuf message to a Ruby Hash (symbol keys).
+          # Optionally converts Timestamp fields to Time and enums to short symbols.
+          #
+          # @param message [Object] Protobuf message instance
+          # @param ruby_friendly [Boolean] If true, timestamps become Time, enums may be shortened
+          # @return [Hash]
+          def to_hash(message, ruby_friendly: false)
+            return {} if message.nil?
+
+            h = message.to_h
+            ruby_friendly ? deep_ruby_friendly(h, message.class.descriptor, message) : h
+          end
+
+          private
+
+          def fetch_value(hash, name)
+            name_sym = name.to_sym
+            return hash[name_sym] if hash.key?(name_sym)
+            return hash[name] if hash.key?(name.to_s)
+
+            nil
+          end
+
+          def set_field(msg, field, value, pool)
+            name = field.name
+            if field.label == :repeated
+              arr = Array(value).map { |v| coerce_single_value(field, v, pool) }
+              msg[name].clear
+              msg[name].concat(arr)
+              return
+            end
+            msg[name] = coerce_single_value(field, value, pool)
+          end
+
+          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+          def coerce_single_value(field, value, pool)
+            case field.type
+            when :enum
+              coerce_enum(field, value)
+            when :message
+              coerce_message(field, value, pool)
+            when :int64, :int32, :uint64, :uint32
+              value.is_a?(Integer) ? value : Integer(value, 10)
+            when :float, :double
+              value.is_a?(Numeric) ? value : Float(value)
+            when :string
+              value.to_s
+            when :bool
+              !!value
+            when :bytes
+              value.to_s.dup.force_encoding(Encoding::ASCII_8BIT)
+            else
+              value
+            end
+          end
+          # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+          # rubocop:disable Metrics/AbcSize
+          def coerce_enum(field, value)
+            return value if value.is_a?(Integer)
+
+            enum_mod = field.subtype.enummodule
+            sym = value.is_a?(Symbol) ? value : value.to_s.to_sym
+            resolved = enum_mod.resolve(sym)
+            return resolved if resolved
+
+            # Try full enum constant name (e.g. ACCOUNT_STATUS_OPEN from :open -> match suffix)
+            enum_mod.constants.each do |c|
+              return enum_mod.const_get(c) if c.to_s.downcase.end_with?(sym.to_s.downcase)
+            end
+            raise ArgumentError, "Unknown enum value for #{field.name}: #{value.inspect}"
+          end
+          # rubocop:enable Metrics/AbcSize
+
+          # rubocop:disable Metrics/MethodLength
+          def coerce_message(field, value, pool)
+            submsg_name = field.submsg_name
+            submsg_class = pool.lookup(submsg_name).msgclass
+
+            if submsg_name == TIMESTAMP_FULL_NAME
+              return time_to_timestamp(value) if value.is_a?(Time)
+              return submsg_class.new(value) if value.is_a?(Hash)
+
+              raise ArgumentError, "Timestamp expects Time or Hash, got #{value.class}"
+            end
+
+            return to_request(submsg_class, value) if value.is_a?(Hash)
+            unless value.is_a?(submsg_class)
+              raise ArgumentError, "Expected Hash or message for #{field.name}, got #{value.class}"
+            end
+
+            value
+          end
+          # rubocop:enable Metrics/MethodLength
+
+          def time_to_timestamp(time)
+            ts = ::Google::Protobuf::Timestamp.new
+            ts.seconds = time.to_i
+            ts.nanos = time.nsec
+            ts
+          end
+
+          def deep_ruby_friendly(hash, _descriptor, _message)
+            return hash_to_time(hash) if timestamp_like_hash?(hash)
+
+            return hash unless hash.is_a?(Hash)
+
+            hash.transform_values { |val| ruby_friendly_value(val) }
+          end
+
+          def ruby_friendly_value(val)
+            case val
+            when Hash then deep_ruby_friendly(val, nil, nil)
+            when Array then val.map { |elem| elem.is_a?(Hash) ? deep_ruby_friendly(elem, nil, nil) : elem }
+            else val
+            end
+          end
+
+          def timestamp_like_hash?(hash)
+            return false unless hash.is_a?(Hash)
+            return false unless hash.key?(:seconds) || hash.key?("seconds")
+            return false unless hash.key?(:nanos) || hash.key?("nanos")
+
+            hash.size <= 2
+          end
+
+          def hash_to_time(hash)
+            sec = hash[:seconds] || hash["seconds"] || 0
+            nano = hash[:nanos] || hash["nanos"] || 0
+            Time.at(sec, nano, :nsec)
+          end
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ModuleLength, Metrics/ClassLength