strix_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3c540b7a6ce319f180344ab79f747935cd377d50815ba1f303cb6b4b95c8612
+  data.tar.gz: 93485bbae481f783eb2eafc08581f73d028369ec627dfa4965c51107dde33b0e
+SHA512:
+  metadata.gz: 56e5fae1c16a06017a9738e92e2f6f42c39bbdc3cd76f6be326282b2e0adb9db74d9e7f948b11659f0ebfc4deb5d0cdc629e810ae8a9300e760b374a43e7d86f
+  data.tar.gz: 4f0e164b09856ae83a82c5d1719efe06df56cd02288bdf996ebf8183891f9c72229beb98742f7f0e8c088a0d1db60e05b542e18824bdea4359e0b34929d1dde7

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,46 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# validate! is intentionally named with bang to indicate it raises exceptions
+Naming/PredicateMethod:
+  AllowedMethods:
+    - validate!
+
+# Gem classes can be longer
+Metrics/ClassLength:
+  Max: 150
+
+# Allow longer methods for configuration and HTTP handling
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - "spec/**/*"
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/ParameterLists:
+  Max: 6
+
+# Exclude spec files from block length - RSpec blocks are naturally long
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-12-31
+
+### Added
+
+- Initial release of StrixRuby client
+- OAuth token management with automatic refresh
+- Global and per-instance configuration
+- `account_id` configurable globally with per-method override
+- API endpoints:
+  - `list_things` - List all things in an account
+  - `list_things_filtered` - List things with type filter
+  - `get_trail_locations` - Get trail locations for a thing
+  - `get_trail_summarized` - Get summarized trail data
+- DateTime/Time parameter support with automatic UTC milliseconds conversion
+- Custom error classes:
+  - `AuthenticationError` - Invalid credentials
+  - `APIError` - API request failures
+  - `ConfigurationError` - Missing configuration
+  - `TokenExpiredError` - Token expiration issues
+- Comprehensive test suite with WebMock

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TechSed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,234 @@
+# 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:
+
+```ruby
+gem 'strix_ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install strix_ruby
+```
+
+## Configuration
+
+### Global Configuration
+
+Configure the gem globally (recommended for Rails applications):
+
+```ruby
+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`:
+
+```ruby
+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:
+
+```ruby
+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
+
+```ruby
+# 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:
+1. Method parameter (if provided)
+2. Configured `account_id` (global or instance)
+3. Token's `meta.business_account_id` (extracted from JWT)
+
+```ruby
+# 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
+
+```ruby
+# 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:
+
+```ruby
+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:
+
+```ruby
+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)
+
+```ruby
+# 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:
+
+```ruby
+# 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:
+
+```ruby
+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.
+
+```bash
+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](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 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](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/strix_ruby/client.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module StrixRuby
+  # Main client for interacting with the Strix Integration API
+  class Client
+    attr_reader :base_url, :account_id
+
+    # Returns the account_id extracted from the JWT token
+    # @return [String, nil] the account_id from token's meta.business_account_id
+    def token_account_id
+      # Ensure token is fetched first
+      @token_manager.access_token
+      @token_manager.token_account_id
+    end
+
+    # Initialize a new client
+    # @param base_url [String] the base URL of the API (optional if globally configured)
+    # @param username [String] the API username (optional if globally configured)
+    # @param password [String] the API password (optional if globally configured)
+    # @param account_id [String, Integer] the default account ID (optional)
+    def initialize(base_url: nil, username: nil, password: nil, account_id: nil)
+      @base_url = base_url || StrixRuby.configuration&.base_url
+      @username = username || StrixRuby.configuration&.username
+      @password = password || StrixRuby.configuration&.password
+      @account_id = account_id || StrixRuby.configuration&.account_id
+
+      validate_configuration!
+
+      @connection = Connection.new(base_url: @base_url)
+      @token_manager = TokenManager.new(
+        connection: @connection,
+        username: @username,
+        password: @password
+      )
+    end
+
+    # List all things in an account
+    # @param account_id [String, Integer, nil] the account ID (uses configured account_id if not provided)
+    # @return [Hash] the API response with things list
+    def list_things(account_id: nil)
+      resolved_account_id = resolve_account_id(account_id)
+      authenticated_get("/v1.5/accounts/#{resolved_account_id}/things")
+    end
+
+    # List things with filters
+    # @param account_id [String, Integer, nil] the account ID (uses configured account_id if not provided)
+    # @param types [String] thing type filter (e.g., 'mrn:thing:vehicle')
+    # @return [Hash] the API response with filtered things list
+    def list_things_filtered(types:, account_id: nil)
+      resolved_account_id = resolve_account_id(account_id)
+      authenticated_get(
+        "/v1.5/things",
+        params: {
+          account_id: resolved_account_id,
+          types: types
+        }
+      )
+    end
+
+    # Get trail locations for a thing
+    # @param thing_id [String, Integer] the thing ID
+    # @param date_from [DateTime, Time] start date (will be converted to UTC milliseconds)
+    # @param date_to [DateTime, Time] end date (will be converted to UTC milliseconds)
+    # @param limit [Integer] number of results per page (default: 100)
+    # @param page [Integer] page number (default: 1)
+    # @param type [String] location type filter (default: 'valid')
+    # @return [Hash] the API response with trail locations
+    def get_trail_locations(thing_id:, date_from:, date_to:, limit: 100, page: 1, type: "valid")
+      authenticated_get(
+        "/v1.5/things/#{thing_id}/trail_locations",
+        params: {
+          _from: datetime_to_ms(date_from),
+          _to: datetime_to_ms(date_to),
+          _limit: limit,
+          _page: page,
+          _type: type
+        }
+      )
+    end
+
+    # Get summarized trail for a thing
+    # @param thing_id [String, Integer] the thing ID
+    # @param date_from [DateTime, Time] start date (will be converted to UTC milliseconds)
+    # @param date_to [DateTime, Time] end date (will be converted to UTC milliseconds)
+    # @param type [String] summary type filter (default: '_valid')
+    # @return [Hash] the API response with trail summary
+    def get_trail_summarized(thing_id:, date_from:, date_to:, type: "_valid")
+      authenticated_get(
+        "/v1.5/things/#{thing_id}/trail_summarized",
+        params: {
+          _from: datetime_to_ms(date_from),
+          _to: datetime_to_ms(date_to),
+          _type: type
+        }
+      )
+    end
+
+    # Force refresh of the access token
+    # @return [String] the new access token
+    def refresh_token!
+      @token_manager.refresh_token
+    end
+
+    # Clear the cached token
+    def clear_token!
+      @token_manager.clear!
+    end
+
+    private
+
+    def validate_configuration!
+      missing = []
+      missing << "base_url" if @base_url.nil? || @base_url.empty?
+      missing << "username" if @username.nil? || @username.empty?
+      missing << "password" if @password.nil? || @password.empty?
+
+      return if missing.empty?
+
+      raise ConfigurationError, "Missing configuration: #{missing.join(", ")}"
+    end
+
+    def authenticated_get(path, params: {})
+      @connection.get(
+        path,
+        params: params,
+        headers: auth_headers
+      )
+    end
+
+    def auth_headers
+      {
+        "Authorization" => "Bearer #{@token_manager.access_token}"
+      }
+    end
+
+    # Resolve account_id with fallback priority:
+    # 1. Method parameter
+    # 2. Configured account_id
+    # 3. Token's meta.business_account_id
+    def resolve_account_id(provided_account_id)
+      resolved = provided_account_id || @account_id || token_account_id
+      unless resolved
+        raise ArgumentError,
+              "account_id is required (provide as argument, configure globally, or it must be present in token)"
+      end
+
+      resolved
+    end
+
+    # Convert a DateTime or Time object to UTC milliseconds
+    # @param datetime [DateTime, Time, Integer] the datetime to convert
+    # @return [Integer] UTC timestamp in milliseconds
+    def datetime_to_ms(datetime)
+      case datetime
+      when Integer
+        datetime
+      when DateTime
+        (datetime.to_time.utc.to_f * 1000).to_i
+      when Time
+        (datetime.utc.to_f * 1000).to_i
+      else
+        raise ArgumentError, "Expected DateTime, Time, or Integer, got #{datetime.class}"
+      end
+    end
+  end
+end

data/lib/strix_ruby/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StrixRuby
+  # Configuration class for storing API credentials and settings
+  class Configuration
+    attr_accessor :base_url, :username, :password, :account_id
+
+    def initialize
+      @base_url = nil
+      @username = nil
+      @password = nil
+      @account_id = nil
+    end
+
+    # Validates that all required configuration is present
+    # @return [Boolean] true if configuration is valid
+    # @raise [ConfigurationError] if configuration is invalid
+    def validate!
+      missing = []
+      missing << "base_url" if base_url.nil? || base_url.empty?
+      missing << "username" if username.nil? || username.empty?
+      missing << "password" if password.nil? || password.empty?
+
+      raise ConfigurationError, "Missing configuration: #{missing.join(", ")}" unless missing.empty?
+
+      true
+    end
+
+    # Check if configuration is valid without raising
+    # @return [Boolean] true if configuration is valid
+    def valid?
+      validate!
+      true
+    rescue ConfigurationError
+      false
+    end
+  end
+end

data/lib/strix_ruby/connection.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module StrixRuby
+  # HTTP connection wrapper using Faraday
+  class Connection
+    attr_reader :base_url
+
+    def initialize(base_url:)
+      @base_url = base_url.chomp("/")
+      @connection = build_connection
+    end
+
+    # Perform a GET request
+    # @param path [String] the API path
+    # @param params [Hash] query parameters
+    # @param headers [Hash] additional headers
+    # @return [Hash] parsed JSON response
+    def get(path, params: {}, headers: {})
+      response = @connection.get(path) do |req|
+        req.params = params unless params.empty?
+        headers.each { |key, value| req.headers[key] = value }
+      end
+
+      handle_response(response)
+    rescue Faraday::ClientError => e
+      handle_faraday_error(e)
+    end
+
+    # Perform a POST request with form data
+    # @param path [String] the API path
+    # @param body [Hash] form data
+    # @param headers [Hash] additional headers
+    # @return [Hash] parsed JSON response
+    def post_form(path, body: {}, headers: {})
+      response = @connection.post(path) do |req|
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        headers.each { |key, value| req.headers[key] = value }
+        req.body = URI.encode_www_form(body)
+      end
+
+      handle_response(response)
+    rescue Faraday::ClientError => e
+      handle_faraday_error(e)
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: @base_url) do |conn|
+        conn.request :url_encoded
+        conn.response :raise_error, include_request: true
+        conn.adapter Faraday.default_adapter
+        conn.headers["Accept"] = "application/json; charset=utf-8"
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        parse_json(response.body)
+      when 401
+        raise AuthenticationError, "Authentication failed (401)"
+      else
+        raise APIError.new(
+          "API request failed with status #{response.status}",
+          status: response.status,
+          body: response.body
+        )
+      end
+    end
+
+    def handle_faraday_error(error)
+      status = error.response&.dig(:status)
+
+      raise AuthenticationError, "Authentication failed (401)" if status == 401
+
+      raise APIError.new(
+        error.message,
+        status: status,
+        body: error.response&.dig(:body)
+      )
+    end
+
+    def parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "raw" => body }
+    end
+  end
+end

data/lib/strix_ruby/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StrixRuby
+  # Custom error classes for the Strix API client
+  class Error < StandardError; end
+
+  # Raised when authentication fails (invalid credentials)
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed. Please check your credentials.")
+      super
+    end
+  end
+
+  # Raised when the API returns an error response
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || "API request failed with status #{status}")
+    end
+  end
+
+  # Raised when the token has expired and cannot be refreshed
+  class TokenExpiredError < Error
+    def initialize(message = "Token has expired and could not be refreshed.")
+      super
+    end
+  end
+
+  # Raised when configuration is missing or invalid
+  class ConfigurationError < Error
+    def initialize(message = "Invalid configuration. Please ensure base_url, username, and password are set.")
+      super
+    end
+  end
+end

data/lib/strix_ruby/token_manager.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "base64"
+require "jwt"
+
+module StrixRuby
+  # Manages OAuth token lifecycle: obtains, caches, and refreshes tokens
+  class TokenManager
+    # Buffer time (in seconds) before actual expiration to refresh token
+    EXPIRATION_BUFFER = 60
+
+    # The account_id extracted from the token's meta.business_account_id
+    attr_reader :token_account_id
+
+    def initialize(connection:, username:, password:)
+      @connection = connection
+      @username = username
+      @password = password
+      @current_token = nil
+      @expires_at = nil
+      @token_account_id = nil
+    end
+
+    # Get a valid access token, refreshing if necessary
+    # @return [String] the access token
+    def access_token
+      refresh_token if token_expired?
+      @current_token
+    end
+
+    # Force a token refresh
+    # @return [String] the new access token
+    def refresh_token
+      response = request_new_token
+      @current_token = response["access_token"]
+      extract_token_data(@current_token)
+      @current_token
+    end
+
+    # Check if the current token is expired or not present
+    # @return [Boolean] true if token needs refresh
+    def token_expired?
+      return true if @current_token.nil? || @expires_at.nil?
+
+      Time.now.to_i >= (@expires_at - EXPIRATION_BUFFER)
+    end
+
+    # Clear the cached token
+    def clear!
+      @current_token = nil
+      @expires_at = nil
+      @token_account_id = nil
+    end
+
+    private
+
+    def request_new_token
+      auth_header = "Basic #{Base64.strict_encode64("#{@username}:#{@password}")}"
+
+      @connection.post_form(
+        "/oauth/token",
+        body: {
+          grant_type: "password",
+          user: @username,
+          password: @password,
+          scope: "all"
+        },
+        headers: {
+          "Authorization" => auth_header
+        }
+      )
+    end
+
+    def extract_token_data(token)
+      # Decode JWT without verification to extract claims
+      # The token signature is verified by the server
+      decoded = JWT.decode(token, nil, false)
+      payload = decoded.first
+
+      @expires_at = extract_expiration(payload)
+      @token_account_id = extract_account_id(payload)
+    rescue JWT::DecodeError
+      # If we can't decode the token, assume it expires in 1 hour
+      @expires_at = Time.now.to_i + 3600
+      @token_account_id = nil
+    end
+
+    def extract_expiration(payload)
+      # exp can be relative (seconds) or absolute (timestamp)
+      exp_value = payload["exp"]
+
+      if exp_value < 100_000_000 # Relative expiration (seconds from iat)
+        iat = payload["iat"] || Time.now.to_i
+        iat + exp_value
+      else
+        exp_value
+      end
+    end
+
+    def extract_account_id(payload)
+      # Extract account_id from meta.business_account_id
+      payload.dig("meta", "business_account_id")
+    end
+  end
+end

data/lib/strix_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StrixRuby
+  VERSION = "0.1.0"
+end

data/lib/strix_ruby.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "strix_ruby/version"
+require_relative "strix_ruby/errors"
+require_relative "strix_ruby/configuration"
+require_relative "strix_ruby/connection"
+require_relative "strix_ruby/token_manager"
+require_relative "strix_ruby/client"
+
+# StrixRuby is a Ruby client for the Strix Integration API
+#
+# @example Global configuration
+#   StrixRuby.configure do |config|
+#     config.base_url = "https://api.example.com"
+#     config.username = "your_username"
+#     config.password = "your_password"
+#   end
+#
+#   client = StrixRuby::Client.new
+#   things = client.list_things(account_id: 123)
+#
+# @example Instance configuration
+#   client = StrixRuby::Client.new(
+#     base_url: "https://api.example.com",
+#     username: "your_username",
+#     password: "your_password"
+#   )
+#   things = client.list_things(account_id: 123)
+#
+module StrixRuby
+  class << self
+    attr_accessor :configuration
+
+    # Configure StrixRuby globally
+    # @yield [Configuration] the configuration object
+    # @example
+    #   StrixRuby.configure do |config|
+    #     config.base_url = "https://api.example.com"
+    #     config.username = "your_username"
+    #     config.password = "your_password"
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    # Reset the configuration to defaults
+    def reset_configuration!
+      self.configuration = Configuration.new
+    end
+  end
+end

data/sig/strix_ruby.rbs

@@ -0,0 +1,4 @@
+module StrixRuby
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: strix_ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nacho Althabe
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby client library for the Strix Integration API. Provides OAuth token
+  management, things listing, and trail location/summary endpoints with automatic
+  token refresh.
+email:
+- nacho@tech-sed.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/strix_ruby.rb
+- lib/strix_ruby/client.rb
+- lib/strix_ruby/configuration.rb
+- lib/strix_ruby/connection.rb
+- lib/strix_ruby/errors.rb
+- lib/strix_ruby/token_manager.rb
+- lib/strix_ruby/version.rb
+- sig/strix_ruby.rbs
+homepage: https://github.com/tech-sed/strix_ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tech-sed/strix_ruby
+  source_code_uri: https://github.com/tech-sed/strix_ruby
+  changelog_uri: https://github.com/tech-sed/strix_ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the Strix Integration API
+test_files: []