Class: TelegramGatewayAdapter::Client

Inherits:
Object
  • Object
show all
Defined in:
app/services/telegram_gateway_adapter/client.rb

Overview

Thin HTTP wrapper around Telegram Gateway’s OTP API.

Endpoint host: gatewayapi.telegram.org API reference: core.telegram.org/gateway/api

Authentication: Bearer API key, sourced from ENV. Tests may inject a key explicitly via the constructor.

Defined Under Namespace

Classes: Result

Constant Summary collapse

BASE_URL = 
'https://gatewayapi.telegram.org'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: ENV.fetch('TELEGRAM_GATEWAY_API_KEY', nil)) ⇒ Client

Returns a new instance of Client.



16
17
18
 
# File 'app/services/telegram_gateway_adapter/client.rb', line 16

def initialize(api_key: ENV.fetch('TELEGRAM_GATEWAY_API_KEY', nil))
  @api_key = api_key
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



14
15
16
 
# File 'app/services/telegram_gateway_adapter/client.rb', line 14

def api_key
  @api_key
end

Instance Method Details

#check_send_ability(phone_number) ⇒ Object 



27
28
29
 
# File 'app/services/telegram_gateway_adapter/client.rb', line 27

def check_send_ability(phone_number)
  parse_result(post('/checkSendAbility', phone_number: phone_number))
end

#check_verification_status(request_id, code) ⇒ Object

Verifies a user-submitted code against a previously sent message.

Response shape from Telegram:

{ ok: true, result: { request_id, verification_status: { status, updated_at, ... } } }

‘status` is one of:

- 'code_valid'                 → user typed the right code
- 'code_invalid'               → user typed the wrong code
- 'code_max_attempts_exceeded' → too many wrong attempts on Telegram's side
- 'expired'                    → ttl elapsed before verification

The returned Result.ok? is TRUE only when status == ‘code_valid’ so the caller can branch with one predicate. The raw ‘verification_status` string is exposed so the caller can map non-ok statuses to specific PinCode outcomes (mismatched / attempt-reached / expired).



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'app/services/telegram_gateway_adapter/client.rb', line 60

def check_verification_status(request_id, code)
  result = parse_result(post('/checkVerificationStatus', request_id: request_id, code: code))

  # If the HTTP envelope itself was not ok (4xx/5xx with ok:false), pass it
  # through unchanged — caller treats it as "unable to verify".
  return result unless result.ok?

  status = result.raw.dig('result', 'verification_status', 'status')

  Result.new(
    ok?: status == 'code_valid',
    request_id: result.request_id,
    verification_status: status,
    raw: result.raw
  )
end

#create_message(options) {|external_ref: result.request_id| ... } ⇒ Object

Yields:

  • (external_ref: result.request_id)

Raises:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'app/services/telegram_gateway_adapter/client.rb', line 77

def create_message(options)
  result = send_verification_message(
    options[:to],
    options[:code],
    request_id: options[:request_id],
    ttl: options[:ttl],
    code_length: options[:code_length]
  )

  raise Error, result.error unless result.ok?

  yield(external_ref: result.request_id)

  result
end

#send_verification_message(phone_number, code, request_id: nil, ttl: nil, code_length: nil) ⇒ Object

When ‘code` is nil/blank, Telegram generates a code of length `code_length` itself and we never see the actual digits — verification then must go through #check_verification_status. When `code` is given, Telegram delivers that exact code (the legacy “we generate, Telegram relays” mode).



35
36
37
38
39
40
41
42
43
 
# File 'app/services/telegram_gateway_adapter/client.rb', line 35

def send_verification_message(phone_number, code, request_id: nil, ttl: nil, code_length: nil)
  effective_length = code_length || code.to_s.length
  payload = { phone_number: phone_number, code_length: effective_length }
  payload[:code] = code if code.present?
  payload[:request_id] = request_id if request_id.present?
  payload[:ttl] = ttl if ttl.present?

  parse_result(post('/sendVerificationMessage', payload))
end