Class: Tcat::WorkerClient

Inherits:
Object
  • Object
show all
Defined in:
lib/tcat/worker_client.rb

Overview

WorkerClient provides a simple interface to query T-Cat tracking via Cloudflare Worker This is an alternative to the direct Query class that goes through your deployed Worker

Defined Under Namespace

Classes: APIError, DeliveryItem, NetworkError, WorkerError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(worker_url = nil, timeout: 30, token: nil) ⇒ WorkerClient

Initialize a new WorkerClient

Parameters:

  • worker_url (String, nil) (defaults to: nil) —

    The URL of your deployed Cloudflare Worker. Falls back to ‘Tcat.configuration.worker_url` when omitted.

  • timeout (Integer) (defaults to: 30) —

    Request timeout in seconds (default: 30)

  • token (String, nil) (defaults to: nil) —

    Bearer token sent in the Authorization header when the Worker is configured with AUTH_TOKEN. Falls back to ‘Tcat.configuration.worker_token` when omitted.

Raises:

  • (ArgumentError) 


26
27
28
29
30
31
32
33
34
 
# File 'lib/tcat/worker_client.rb', line 26

def initialize(worker_url = nil, timeout: 30, token: nil)
  url = worker_url || Tcat.configuration.worker_url
  raise ArgumentError, 'Worker URL must be configured' if url.nil? || url.empty?

  @worker_url = url.chomp('/')
  @timeout = timeout
  @token = token || Tcat.configuration.worker_token
  validate_url!
end

Instance Attribute Details

#worker_url ⇒ Object (readonly)

Returns the value of attribute worker_url.



17
18
19
 
# File 'lib/tcat/worker_client.rb', line 17

def worker_url
  @worker_url
end

Instance Method Details

#healthy? ⇒ Boolean

Check if the Worker is healthy

Returns:

  • (Boolean) —

    true if Worker responds to health check



91
92
93
94
95
96
97
98
 
# File 'lib/tcat/worker_client.rb', line 91

def healthy?
  uri = URI("#{@worker_url}/health")
  response = make_request(uri)
  data = JSON.parse(response.body, symbolize_names: true)
  data[:status] == 'ok'
rescue StandardError
  false
end

#history(tracking_number) ⇒ Array<DeliveryItem>

Get the complete delivery history

Parameters:

  • tracking_number (String) —

    The tracking number to query

Returns:



67
68
69
70
71
72
73
74
 
# File 'lib/tcat/worker_client.rb', line 67

def history(tracking_number)
  result = query(tracking_number)
  items = result[:items] || []
  items.map { |item| parse_delivery_item(item) }
rescue WorkerError => e
  warn "Error getting history: #{e.message}" if $DEBUG
  []
end

#latest_status(tracking_number) ⇒ DeliveryItem?

Get the latest delivery status

Parameters:

  • tracking_number (String) —

    The tracking number to query

Returns:



79
80
81
82
83
84
85
86
87
 
# File 'lib/tcat/worker_client.rb', line 79

def latest_status(tracking_number)
  result = query(tracking_number)
  return nil unless result[:latest]

  parse_delivery_item(result[:latest])
rescue WorkerError => e
  warn "Error getting latest status: #{e.message}" if $DEBUG
  nil
end

#query(tracking_number) ⇒ Hash

Query a tracking number through the Worker

Parameters:

  • tracking_number (String) —

    The tracking number to query

Returns:

  • (Hash) —

    Parsed response from the Worker



39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/tcat/worker_client.rb', line 39

def query(tracking_number)
  raise ArgumentError, 'Tracking number cannot be nil or empty' if tracking_number.nil? || tracking_number.empty?

  uri = URI("#{@worker_url}/query")
  uri.query = URI.encode_www_form(no: tracking_number)

  response = make_request(uri)
  parse_response(response)
rescue SocketError, Net::HTTPError => e
  raise NetworkError, "Network error: #{e.message}"
rescue JSON::ParserError => e
  raise APIError, "Invalid JSON response: #{e.message}"
end

#status_code(tracking_number) ⇒ Symbol?

Get the current status code for a tracking number

Parameters:

  • tracking_number (String) —

    The tracking number to query

Returns:

  • (Symbol, nil) —

    Status code symbol or nil if error



56
57
58
59
60
61
62
 
# File 'lib/tcat/worker_client.rb', line 56

def status_code(tracking_number)
  result = query(tracking_number)
  result[:status_code]&.to_sym
rescue WorkerError => e
  warn "Error getting status: #{e.message}" if $DEBUG
  nil
end