ruby-fiix-cmms-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9869f6020778153f7836b0d77af9238ffa5f334192098a76bb421117cbd70d8
+  data.tar.gz: c065c5d1e9a47cf28e70ecda4c9698d6b5212f78105302bccdb129e40c7e65cf
+SHA512:
+  metadata.gz: 6273384a2acc4ba6297dac1cf182b97f621446e95f825b1172e70fb99bcf46e4839b1aecc429c19d7d83cfb865fc2c9acb2167e9c7787a3daf206a35d835142a
+  data.tar.gz: da1cc68df6842f83a835442ecd6d5f2fb59fc992106bc7c9dc6707bbbc0b6062099d5e4659158afbf5b79eae2a16198626fa10134920600506545effc0e0f6b2

data/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake test

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Ruby client gem for the Fiix CMMS (Computerized Maintenance Management System) REST API. Requires Ruby >= 3.2.0. Zero runtime dependencies (uses stdlib: net/http, openssl, json).
+
+**Goal:** Idiomatic Ruby gem covering the full Fiix CMMS API surface, usable standalone or in Rails apps.
+
+### Reference Clients
+
+- **Python** (`Saint-Solutions/python-fiix-cmms-client`): HMAC-SHA256 auth, 5 operations.
+- **JS** (`fiixlabs/fiix-cmms-client-js` v2.41.0): 8 operations including FindByIdRequest, RpcRequest, and file upload.
+
+This gem covers all 8 operations.
+
+## Commands
+
+- **Install dependencies:** `bin/setup` or `bundle install`
+- **Run all tests:** `bundle exec rake test` (or just `rake`, test is the default task)
+- **Run a single test file:** `bundle exec ruby -Ilib:test test/ruby/fiix/cmms/test_api_client.rb`
+- **Run a single test method:** `bundle exec ruby -Ilib:test test/ruby/fiix/cmms/test_api_client.rb --name test_find_sends_find_request`
+- **Interactive console:** `bin/console`
+- **Install gem locally:** `bundle exec rake install`
+
+## Architecture
+
+- **Module namespace:** `Ruby::Fiix::Cmms::Client`
+- **Entry point:** `lib/ruby/fiix/cmms/client.rb` — requires all modules, provides `configure` / `reset_configuration!`
+- **Core files:**
+  - `client/version.rb` — `VERSION` constant
+  - `client/errors.rb` — `Error`, `ConfigurationError`, `ApiError`, `ConnectionError`
+  - `client/configuration.rb` — credential holder with `validate!`
+  - `client/auth.rb` — `Auth.base_url` and `Auth.sign` (HMAC-SHA256)
+  - `client/response.rb` — wraps `Net::HTTPResponse` with `body`, `success?`, `status`, `[]`, `to_h`
+  - `client/api_client.rb` — `ApiClient` class with 8 operations: `create`, `find`, `find_by_id`, `update`, `delete`, `rpc`, `batch`, `upload_file`
+- **Test framework:** Minitest + WebMock (tests in `test/`)
+- **Type signatures:** `sig/` directory (RBS)
+
+## Development Principles
+
+### TDD (Test-Driven Development)
+
+Follow the Red-Green-Refactor cycle strictly:
+1. **Red:** Write a failing test first — no production code without a failing test.
+2. **Green:** Write the minimum code to make the test pass.
+3. **Refactor:** Clean up while keeping tests green.
+
+Tests go in `test/` using Minitest. Write tests before implementation, not after.
+
+### Clean Code (Uncle Bob)
+
+- **Small functions:** Each method does one thing. If a method needs a comment to explain *what* it does, it should be extracted or renamed.
+- **Meaningful names:** Classes, methods, and variables should reveal intent. No abbreviations or cryptic names.
+- **Single Responsibility Principle:** Each class has one reason to change.
+- **One level of abstraction per function:** Don't mix high-level orchestration with low-level details in the same method.
+- **No dead code:** Don't leave commented-out code, unused methods, or unreachable branches.
+- **DRY but not premature:** Extract duplication only when the pattern is clear (Rule of Three).
+- **Command-Query Separation:** Methods either do something (command) or return something (query), not both.
+- **Prefer exceptions over error codes:** Use custom error classes inheriting from `Ruby::Fiix::Cmms::Client::Error`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ruby-fiix-cmms-client" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["hi@ronaldlangeveld.com"](mailto:"hi@ronaldlangeveld.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ronald Langeveld
+
+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,142 @@
+# Ruby Fiix CMMS Client
+
+A Ruby gem for the [Fiix CMMS](https://www.fiixsoftware.com/) REST API with HMAC-SHA256 authentication. Zero runtime dependencies.
+
+Supports all core API operations: find, find by ID, create, update, delete, RPC, batch, and file uploads.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ruby-fiix-cmms-client"
+```
+
+Then run `bundle install`.
+
+Or install directly:
+
+```bash
+gem install ruby-fiix-cmms-client
+```
+
+## Usage
+
+### Direct instantiation
+
+```ruby
+require "ruby/fiix/cmms/client"
+
+client = Ruby::Fiix::Cmms::Client::ApiClient.new(
+  subdomain: "mycompany",
+  api_key: "your-app-key",
+  access_key: "your-access-key",
+  api_secret: "your-api-secret"
+)
+
+# Find records
+response = client.find(className: "Account", fields: "id,strCode,strDescription")
+response.body     # => parsed Hash
+response.success? # => true
+response.status   # => 200
+
+# Find by ID
+response = client.find_by_id(className: "Asset", id: 12345, fields: "id,strName")
+
+# Create
+response = client.create(
+  className: "WorkOrder",
+  fields: "id",
+  object: { "strDescription" => "Fix pump" }
+)
+
+# Update
+response = client.update(
+  className: "WorkOrder",
+  object: { "id" => 1, "strDescription" => "Fix pump - urgent" }
+)
+
+# Delete
+response = client.delete(className: "WorkOrder", objects: [{ "id" => 1 }])
+
+# RPC (remote procedure call)
+response = client.rpc(className: "User", action: "getPermissions")
+
+# Batch (multiple operations in one request)
+response = client.batch(
+  requests: [
+    { "_maCn" => "FindRequest", "className" => "Account", "fields" => "id,strCode" },
+    { "_maCn" => "FindRequest", "className" => "PurchaseOrder", "fields" => "id,intCode" }
+  ]
+)
+
+# File upload
+file = File.open("document.pdf")
+response = client.upload_file(
+  className: "CMAFileContainer",
+  file: file,
+  description: "Maintenance report"
+)
+```
+
+### Rails initializer pattern
+
+```ruby
+# config/initializers/fiix.rb
+Ruby::Fiix::Cmms::Client.configure do |c|
+  c.subdomain  = ENV["FIIX_SUBDOMAIN"]
+  c.api_key    = ENV["FIIX_API_KEY"]
+  c.access_key = ENV["FIIX_ACCESS_KEY"]
+  c.api_secret = ENV["FIIX_API_SECRET"]
+end
+
+# Anywhere in your app
+client = Ruby::Fiix::Cmms::Client::ApiClient.new  # uses global config
+```
+
+### Response object
+
+All operations return a `Ruby::Fiix::Cmms::Client::Response`:
+
+```ruby
+response = client.find(className: "Account", fields: "id")
+
+response.body          # => parsed JSON as Hash
+response.success?      # => true/false (based on HTTP status)
+response.status        # => 200 (integer)
+response["key"]        # => shorthand for response.body["key"]
+response.to_h          # => Hash (empty hash if body isn't JSON)
+response.http_response # => raw Net::HTTPResponse
+```
+
+### Error handling
+
+```ruby
+begin
+  client.find(className: "Account")
+rescue Ruby::Fiix::Cmms::Client::ConfigurationError => e
+  # Missing or invalid credentials
+rescue Ruby::Fiix::Cmms::Client::ConnectionError => e
+  # Network connectivity issues
+rescue Ruby::Fiix::Cmms::Client::ApiError => e
+  # API-level errors (e.response holds the Response object)
+rescue Ruby::Fiix::Cmms::Client::Error => e
+  # Catch-all for any gem error
+end
+```
+
+## Development
+
+```bash
+bin/setup          # Install dependencies
+rake test          # Run tests
+bin/console        # Interactive console
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/ronaldlangeveld/ruby-fiix-cmms-client).
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/ruby/fiix/cmms/client/api_client.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        class ApiClient
+          OPERATIONS = {
+            create: "AddRequest",
+            find: "FindRequest",
+            find_by_id: "FindByIdRequest",
+            update: "ChangeRequest",
+            delete: "RemoveRequest",
+            rpc: "RpcRequest",
+            batch: "BatchRequest"
+          }.freeze
+
+          DEFAULT_CLIENT_VERSION = { "clientVersion" => { "major" => 2, "minor" => 8, "patch" => 1 } }.freeze
+
+          def initialize(subdomain: nil, api_key: nil, access_key: nil, api_secret: nil)
+            config = Client.configuration
+            @subdomain  = subdomain  || config&.subdomain
+            @api_key    = api_key    || config&.api_key
+            @access_key = access_key || config&.access_key
+            @api_secret = api_secret || config&.api_secret
+
+            validate_credentials!
+
+            @base_url  = Auth.base_url(@subdomain, @api_key, @access_key)
+            @signature = Auth.sign(@api_secret, @base_url)
+            @uri       = URI.parse(@base_url)
+          end
+
+          OPERATIONS.each do |method_name, request_type|
+            define_method(method_name) do |context|
+              payload = { "_maCn" => request_type }
+                .merge(DEFAULT_CLIENT_VERSION)
+                .merge(normalize_context(context))
+              request(payload)
+            end
+          end
+
+          def upload_file(context)
+            normalized = normalize_context(context)
+            file = normalized.delete("file")
+            multipart_request(normalized, file)
+          end
+
+          private
+
+          def validate_credentials!
+            Configuration.new(
+              subdomain: @subdomain,
+              api_key: @api_key,
+              access_key: @access_key,
+              api_secret: @api_secret
+            ).validate!
+          end
+
+          def normalize_context(context)
+            context.transform_keys(&:to_s)
+          end
+
+          def request(payload)
+            http = build_http
+            req = Net::HTTP::Post.new(@uri.request_uri)
+            req["Authorization"] = @signature
+            req["Content-Type"] = "text/plain;charset=utf-8"
+            req.body = JSON.generate(payload)
+
+            Response.new(http.request(req))
+          rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+            raise ConnectionError, "Failed to connect to Fiix API: #{e.message}"
+          end
+
+          def multipart_request(params, file)
+            boundary = "----RubyFiixCmms#{SecureRandom.hex(16)}"
+            body = build_multipart_body(params, file, boundary)
+
+            http = build_http
+            req = Net::HTTP::Post.new(@uri.request_uri)
+            req["Authorization"] = @signature
+            req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+            req.body = body
+
+            Response.new(http.request(req))
+          rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+            raise ConnectionError, "Failed to connect to Fiix API: #{e.message}"
+          end
+
+          def build_http
+            http = Net::HTTP.new(@uri.host, @uri.port)
+            http.use_ssl = true
+            http
+          end
+
+          def build_multipart_body(params, file, boundary)
+            parts = []
+
+            params.each do |key, value|
+              parts << "--#{boundary}\r\n" \
+                       "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n" \
+                       "#{value}\r\n"
+            end
+
+            if file
+              filename = file.respond_to?(:path) ? File.basename(file.path) : "upload"
+              file_content = file.respond_to?(:read) ? file.read : file
+              parts << "--#{boundary}\r\n" \
+                       "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n" \
+                       "Content-Type: application/octet-stream\r\n\r\n" \
+                       "#{file_content}\r\n"
+            end
+
+            parts << "--#{boundary}--\r\n"
+            parts.join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/fiix/cmms/client/auth.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        module Auth
+          module_function
+
+          def base_url(subdomain, api_key, access_key)
+            "https://#{subdomain}.macmms.com/api/" \
+              "?service=cmms&appKey=#{api_key}&accessKey=#{access_key}" \
+              "&signatureMethod=HmacSHA256&signatureVersion=1"
+          end
+
+          def sign(api_secret, url)
+            message = url.sub("https://", "")
+            OpenSSL::HMAC.hexdigest("SHA256", api_secret, message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/fiix/cmms/client/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        class Configuration
+          REQUIRED_ATTRIBUTES = %i[subdomain api_key access_key api_secret].freeze
+
+          attr_accessor :subdomain, :api_key, :access_key, :api_secret
+
+          def initialize(subdomain: nil, api_key: nil, access_key: nil, api_secret: nil)
+            @subdomain = subdomain
+            @api_key = api_key
+            @access_key = access_key
+            @api_secret = api_secret
+          end
+
+          def validate!
+            REQUIRED_ATTRIBUTES.each do |attr|
+              value = send(attr)
+              raise ConfigurationError, "#{attr} is required" if value.nil? || value.to_s.empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/fiix/cmms/client/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        class Error < StandardError; end
+
+        class ConfigurationError < Error; end
+
+        class ConnectionError < Error; end
+
+        class ApiError < Error
+          attr_reader :response
+
+          def initialize(message, response: nil)
+            @response = response
+            super(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/fiix/cmms/client/response.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        class Response
+          attr_reader :http_response
+
+          def initialize(http_response)
+            @http_response = http_response
+          end
+
+          def body
+            @body ||= JSON.parse(http_response.body)
+          rescue JSON::ParserError
+            @body = http_response.body
+          end
+
+          def success?
+            http_response.is_a?(Net::HTTPSuccess)
+          end
+
+          def status
+            http_response.code.to_i
+          end
+
+          def [](key)
+            body[key]
+          end
+
+          def to_h
+            body.is_a?(Hash) ? body : {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/fiix/cmms/client/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        VERSION = "0.1.0"
+      end
+    end
+  end
+end

data/lib/ruby/fiix/cmms/client.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "client/version"
+require_relative "client/errors"
+require_relative "client/configuration"
+require_relative "client/auth"
+require_relative "client/response"
+require_relative "client/api_client"
+
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        class << self
+          attr_accessor :configuration
+
+          def configure
+            self.configuration ||= Configuration.new
+            yield(configuration)
+          end
+
+          def reset_configuration!
+            self.configuration = nil
+          end
+        end
+      end
+    end
+  end
+end

data/sig/ruby/fiix/cmms/client.rbs

@@ -0,0 +1,10 @@
+module Ruby
+  module Fiix
+    module Cmms
+      module Client
+        VERSION: String
+        # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: ruby-fiix-cmms-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ronald Langeveld
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A Ruby gem wrapping the Fiix CMMS (Computerized Maintenance Management
+  System) REST API with HMAC-SHA256 authentication. Supports all core operations:
+  find, create, update, delete, batch, RPC, and file uploads. Zero runtime dependencies.'
+email:
+- hi@ronaldlangeveld.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ruby/fiix/cmms/client.rb
+- lib/ruby/fiix/cmms/client/api_client.rb
+- lib/ruby/fiix/cmms/client/auth.rb
+- lib/ruby/fiix/cmms/client/configuration.rb
+- lib/ruby/fiix/cmms/client/errors.rb
+- lib/ruby/fiix/cmms/client/response.rb
+- lib/ruby/fiix/cmms/client/version.rb
+- sig/ruby/fiix/cmms/client.rbs
+homepage: https://github.com/ronaldlangeveld/ruby-fiix-cmms-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ronaldlangeveld/ruby-fiix-cmms-client
+  source_code_uri: https://github.com/ronaldlangeveld/ruby-fiix-cmms-client
+  changelog_uri: https://github.com/ronaldlangeveld/ruby-fiix-cmms-client/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Fiix CMMS REST API
+test_files: []