StrixRuby

A Ruby client library for the Strix Integration API. Provides OAuth token management, things listing, and trail location/summary endpoints with automatic token refresh.

Features

🔐 Automatic OAuth Token Management - Tokens are obtained automatically and refreshed when expired
📍 Trail Locations & Summaries - Query vehicle/thing trail data with date ranges
🕐 DateTime Support - Pass DateTime or Time objects, automatically converted to UTC milliseconds
⚙️ Flexible Configuration - Global or per-instance configuration
🧪 Well Tested - Comprehensive test suite with mocked API responses

Installation

Add this line to your application's Gemfile:

gem 'strix_ruby'

And then execute:

bundle install

Or install it yourself as:

gem install strix_ruby

Configuration

Global Configuration

Configure the gem globally (recommended for Rails applications):

StrixRuby.configure do |config|
  config.base_url = "https://api.strix.example.com"
  config.username = "your_username"
  config.password = "your_password"
  config.account_id = "your_default_account_id"  # optional
end

Rails Initializer

Create a file config/initializers/strix_ruby.rb:

StrixRuby.configure do |config|
  config.base_url = ENV["STRIX_API_URL"]
  config.username = ENV["STRIX_USERNAME"]
  config.password = ENV["STRIX_PASSWORD"]
  config.account_id = ENV["STRIX_ACCOUNT_ID"]  # optional
end

Per-Instance Configuration

You can also configure each client instance separately:

client = StrixRuby::Client.new(
  base_url: "https://api.strix.example.com",
  username: "your_username",
  password: "your_password",
  account_id: "your_account_id"  # optional
)

Usage

Create a Client

# Using global configuration
client = StrixRuby::Client.new

# Or with instance configuration
client = StrixRuby::Client.new(
  base_url: "https://api.strix.example.com",
  username: "your_username",
  password: "your_password"
)

List Things

The account_id is resolved in this priority order:

Method parameter (if provided)
Configured account_id (global or instance)
Token's meta.business_account_id (extracted from JWT)

# Uses account_id from configuration or token
things = client.list_things

# Override with specific account_id
things = client.list_things(account_id: "12345")

# Access the account_id from the token
client.token_account_id  # => "mrn:account:business:..."

List Things with Filter

# Get only vehicles
vehicles = client.list_things_filtered(types: "mrn:thing:vehicle")

# Specify account_id
vehicles = client.list_things_filtered(
  account_id: "12345",
  types: "mrn:thing:vehicle"
)

Get Trail Locations

Query trail locations for a thing within a date range:

locations = client.get_trail_locations(
  thing_id: "67890",
  date_from: DateTime.now - 1,  # 1 day ago
  date_to: DateTime.now,
  limit: 100,                    # optional, default: 10
  page: 1,                       # optional, default: 1
  type: "valid"                  # optional, default: "valid"
)

Get Trail Summary

Get a summarized view of trail data:

summary = client.get_trail_summarized(
  thing_id: "67890",
  date_from: DateTime.new(2024, 1, 1, 0, 0, 0, "-03:00"),
  date_to: DateTime.new(2024, 1, 31, 23, 59, 59, "-03:00"),
  type: "_valid"                 # optional, default: "_valid"
)

# Response includes:
# - max_speed: Maximum speed in Km/h
# - distance: Distance in meters
# - time_with_contact_off: Time without contact (seconds)
# - time_in_movement_and_contact_on: Time moving with contact (seconds)
# - time_stopped_and_contact_on: Time stopped with contact (seconds)

Date/Time Handling

The API expects timestamps in UTC milliseconds. The client accepts:

DateTime objects: Converted to UTC milliseconds automatically
Time objects: Converted to UTC milliseconds automatically
Integer timestamps: Used as-is (must be in milliseconds)

# All of these work:
client.get_trail_locations(
  thing_id: "67890",
  date_from: DateTime.now - 1,        # DateTime
  date_to: Time.now                    # Time
)

client.get_trail_locations(
  thing_id: "67890",
  date_from: 1704067200000,            # Integer (milliseconds)
  date_to: 1704153600000
)

Token Management

Tokens are managed automatically, but you can control them manually if needed:

# Force token refresh
client.refresh_token!

# Clear cached token (next request will fetch new token)
client.clear_token!

Error Handling

The gem raises specific errors for different failure cases:

begin
  client.list_things
rescue StrixRuby::AuthenticationError => e
  # Invalid credentials (401)
  puts "Authentication failed: #{e.message}"
rescue StrixRuby::APIError => e
  # Other API errors
  puts "API error (#{e.status}): #{e.message}"
  puts "Response body: #{e.body}"
rescue StrixRuby::ConfigurationError => e
  # Missing configuration
  puts "Configuration error: #{e.message}"
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

bundle install
bundle exec rspec

You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tech-sed/strix_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the StrixRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

strix_ruby

Runtime