d4h_api 2.0.0

data/d4h_api.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "d4h_api"
+  spec.version = "2.0.0"
+  spec.authors = ["Pawel Osiczko"]
+  spec.email = ["p.osiczko@tetrapyloctomy.org"]
+  spec.homepage = "https://github.com/rockymountainrescue/d4h_api"
+  spec.summary = "D4H API in Ruby"
+  spec.license = "Hippocratic-2.1"
+  spec.rdoc_options = ["--main", "README.md", "--markup", "tomdoc"]
+
+  spec.metadata = {"label" => "D4H", "rubygems_mfa_required" => "true"}
+
+  spec.signing_key = Gem.default_key_path
+  spec.cert_chain = [Gem.default_cert_path]
+
+  spec.required_ruby_version = ">= 4.0"
+  spec.add_dependency("ostruct", "~> 0.6")
+  spec.add_dependency("zeitwerk", "~> 2.6")
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+
+  spec.add_dependency("dotenv", "~> 3.0")
+  spec.add_dependency("faraday", "~> 2.13")
+  spec.add_dependency("faraday-retry", "~> 2.4")
+end

data/lib/d4h/api/client.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/middleware"
+require "faraday/retry"
+
+module D4H
+  module API
+    # Public: HTTP client for the D4H Developer API v3.
+    #
+    # Wraps a Faraday connection with Bearer token authentication and
+    # provides accessor methods for every supported API resource.
+    #
+    # The client builds URL paths as `v3/{context}/{context_id}/{resource}`,
+    # where context is typically "team" but can be "organisation" for
+    # organisation-scoped endpoints.
+    #
+    # Examples
+    #
+    #   # Team context (default)
+    #   client = D4H::API::Client.new(
+    #     api_key:    ENV.fetch("D4H_TOKEN"),
+    #     context_id: 42,
+    #   )
+    #   client.member.list
+    #   client.event.show(id: 1)
+    #
+    #   # Organisation context
+    #   client = D4H::API::Client.new(
+    #     api_key:    ENV.fetch("D4H_TOKEN"),
+    #     context:    "organisation",
+    #     context_id: 99,
+    #   )
+    class Client
+      # Internal: Default base URL for the D4H API. Override via D4H_BASE_URL
+      # env var or the base_url: constructor parameter.
+      DEFAULT_BASE_URL = "https://api.team-manager.us.d4h.com"
+
+      # Public: Returns the base URL, API token, Faraday adapter, context type,
+      # context ID, max retries, and retry interval.
+      attr_reader :base_url, :api_key, :adapter, :context, :context_id, :max_retries, :retry_interval
+
+      # Public: Initialize a new D4H API client.
+      #
+      # api_key:        - A String Bearer token for API authentication.
+      # context:        - The context scope, either "team" (default) or "organisation".
+      # context_id:     - The Integer ID of the team or organisation.
+      # base_url:       - The base URL for the D4H API. Defaults to D4H_BASE_URL env
+      #                   var, or "https://api.team-manager.us.d4h.com" if unset.
+      #                   Change this for EU or other regional endpoints.
+      # adapter:        - The Faraday adapter to use (default: Faraday.default_adapter).
+      #                   Pass `[:test, stubs]` for testing with Faraday::Adapter::Test.
+      # max_retries:    - Integer number of retries for transient errors (default: 3).
+      #                   Set to 0 to disable retries.
+      # retry_interval: - Float base interval in seconds between retries (default: 1).
+      #                   Set to 0 in tests to avoid sleeping.
+      def initialize(api_key:, context: "team", context_id:,
+        base_url: ENV.fetch("D4H_BASE_URL", DEFAULT_BASE_URL),
+        adapter: Faraday.default_adapter,
+        max_retries: MAX_RETRIES, retry_interval: RETRY_INTERVAL)
+        @api_key = api_key
+        @base_url = base_url
+        @context = context
+        @context_id = context_id
+        @adapter = adapter
+        @max_retries = max_retries
+        @retry_interval = retry_interval
+      end
+
+      # Public: Returns the versioned, context-scoped path prefix.
+      #
+      # Examples
+      #
+      #   client.base_path  # => "v3/team/42"
+      def base_path
+        "v3/#{context}/#{context_id}"
+      end
+
+      # Internal: Maximum number of retries for transient errors (429, 5xx).
+      MAX_RETRIES = 3
+
+      # Internal: Base interval in seconds for exponential backoff.
+      RETRY_INTERVAL = 1
+
+      # Internal: Maximum backoff interval in seconds.
+      MAX_RETRY_INTERVAL = 30
+
+      # Internal: Backoff factor — each retry doubles the wait time.
+      RETRY_BACKOFF_FACTOR = 2
+
+      # Internal: HTTP status codes that are transient and safe to retry.
+      RETRIABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+      # Internal: HTTP methods to retry. All methods are retriable for
+      # transient server errors since the request may not have been processed.
+      RETRIABLE_METHODS = %i[delete get head options patch post put].freeze
+
+      # Public: Returns the memoized Faraday connection.
+      #
+      # Configured with URL-encoded request encoding, JSON response parsing,
+      # exponential backoff retry on transient errors, and the chosen adapter.
+      #
+      # The retry middleware retries on 429 and 5xx status codes up to
+      # max_retries times with exponential backoff (1s, 2s, 4s) capped at
+      # 30s. It also respects the D4H API's ratelimit headers for wait times.
+      # Set max_retries: 0 to disable retries.
+      def connection
+        @connection ||= Faraday.new do |f|
+          f.url_prefix = base_url
+          f.request(:url_encoded)
+          if max_retries > 0
+            f.request(:retry,
+              max: max_retries,
+              interval: retry_interval,
+              max_interval: MAX_RETRY_INTERVAL,
+              backoff_factor: RETRY_BACKOFF_FACTOR,
+              retry_statuses: RETRIABLE_STATUSES,
+              methods: RETRIABLE_METHODS,
+              retry_block: ->(env:, options:, retry_count:, exception:, will_retry_in:) {
+                Kernel.warn("[D4H] Retry #{retry_count + 1}/#{options.max} for #{env[:method].upcase} " \
+                  "#{env[:url]} (#{exception.class}) in #{will_retry_in}s")
+              })
+          end
+          f.response(:json, content_type: "application/json")
+          f.adapter(*Array(adapter))
+        end
+      end
+
+      # Public: Returns a short string representation that hides the API key.
+      def inspect
+        "#<D4H::Client>"
+      end
+
+      # -- Resource accessors --
+      #
+      # Each method returns a new Resource instance bound to this client.
+      # Resources are organized by domain below.
+
+      # Animals
+      def animal = AnimalResource.new(self)
+      def animal_group = AnimalGroupResource.new(self)
+      def animal_group_membership = AnimalGroupMembershipResource.new(self)
+      def animal_qualification = AnimalQualificationResource.new(self)
+
+      # Attendance
+      def attendance = AttendanceResource.new(self)
+
+      # Custom Fields
+      def custom_field = CustomFieldResource.new(self)
+      def custom_field_for_entity = CustomFieldForEntityResource.new(self)
+
+      # Documents
+      def document = DocumentResource.new(self)
+
+      # Equipment
+      def equipment = EquipmentResource.new(self)
+      def equipment_brand = EquipmentBrandResource.new(self)
+      def equipment_category = EquipmentCategoryResource.new(self)
+      def equipment_fund = EquipmentFundResource.new(self)
+      def equipment_inspection = EquipmentInspectionResource.new(self)
+      def equipment_inspection_result = EquipmentInspectionResultResource.new(self)
+      def equipment_inspection_step = EquipmentInspectionStepResource.new(self)
+      def equipment_inspection_step_result = EquipmentInspectionStepResultResource.new(self)
+      def equipment_kind = EquipmentKindResource.new(self)
+      def equipment_location = EquipmentLocationResource.new(self)
+      def equipment_model = EquipmentModelResource.new(self)
+      def equipment_retired_reason = EquipmentRetiredReasonResource.new(self)
+      def equipment_supplier = EquipmentSupplierResource.new(self)
+      def equipment_supplier_ref = EquipmentSupplierRefResource.new(self)
+      def equipment_usage = EquipmentUsageResource.new(self)
+
+      # Events & Incidents
+      def event = EventResource.new(self)
+      def exercise = ExerciseResource.new(self)
+      def incident = IncidentResource.new(self)
+      def incident_involved_injury = IncidentInvolvedInjuryResource.new(self)
+      def incident_involved_metadata = IncidentInvolvedMetadataResource.new(self)
+      def incident_involved_person = IncidentInvolvedPersonResource.new(self)
+
+      # Handlers
+      def handler_group = HandlerGroupResource.new(self)
+      def handler_group_membership = HandlerGroupMembershipResource.new(self)
+      def handler_qualification = HandlerQualificationResource.new(self)
+
+      # Health & Safety
+      def health_safety_category = HealthSafetyCategoryResource.new(self)
+      def health_safety_report = HealthSafetyReportResource.new(self)
+      def health_safety_severity = HealthSafetySeverityResource.new(self)
+
+      # Members
+      def member = MemberResource.new(self)
+      def member_custom_status = MemberCustomStatusResource.new(self)
+      def member_group = MemberGroupResource.new(self)
+      def member_group_membership = MemberGroupMembershipResource.new(self)
+      def member_qualification = MemberQualificationResource.new(self)
+      def member_qualification_award = MemberQualificationAwardResource.new(self)
+      def member_retired_reason = MemberRetiredReasonResource.new(self)
+
+      # Operations & Organization
+      def customer_identifier = CustomerIdentifierResource.new(self)
+      def d4h_module = D4hModuleResource.new(self)
+      def d4h_task = D4hTaskResource.new(self)
+      def duty = DutyResource.new(self)
+      def location_bookmark = LocationBookmarkResource.new(self)
+      def organisation = OrganisationResource.new(self)
+      def repair = RepairResource.new(self)
+      def resource_bundle = ResourceBundleResource.new(self)
+      def role = RoleResource.new(self)
+      def search = SearchResultResource.new(self)
+      def tag = TagResource.new(self)
+      def team = TeamResource.new(self)
+      def whiteboard = WhiteboardResource.new(self)
+      def whoami = WhoamiResource.new(self)
+    end
+  end
+end

data/lib/d4h/api/collection.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    # Public: An Enumerable wrapper around a paginated D4H API list response.
+    #
+    # Parses the standard D4H v3 list envelope — which contains "results",
+    # "page", "pageSize", and "totalSize" — and converts each result into
+    # the given model class.
+    #
+    # Includes Enumerable, so you can call `map`, `select`, `first`, `count`,
+    # and any other Enumerable method directly on a collection.
+    #
+    # Examples
+    #
+    #   collection = client.member.list
+    #   collection.total_size          # => 90
+    #   collection.page                # => 0
+    #   collection.map(&:name)         # => ["Alice", "Bob", ...]
+    #   collection.first.status        # => "OPERATIONAL"
+    #   collection.select { |m| m.status == "OPERATIONAL" }
+    #
+    #   # Raw JSON envelope
+    #   collection.to_json  # => {"results" => [...], "page" => 0, ...}
+    class Collection
+      # Public: Returns the Array of Model instances from this page.
+      # Public: Returns the zero-based page number.
+      # Public: Returns the page size (number of results per page).
+      # Public: Returns the total number of results across all pages.
+      # Public: Returns the original JSON hash envelope.
+      attr_reader :results, :page, :page_size, :total_size, :to_json
+
+      # Public: Initialize a Collection from a parsed JSON response body.
+      #
+      # body        - A Hash with "results", "page", "pageSize", "totalSize" keys.
+      # model_class - The Model subclass to wrap each result in (e.g. Member, Event).
+      def initialize(body, model_class:)
+        @to_json = body
+        @results = (body["results"] || []).map { |attrs| model_class.new(attrs) }
+        @page = body["page"]
+        @page_size = body["pageSize"]
+        @total_size = body["totalSize"]
+      end
+
+      include Enumerable
+
+      # Public: Yield each Model in the results array.
+      #
+      # Yields each Model instance.
+      def each(&block)
+        results.each(&block)
+      end
+    end
+  end
+end

data/lib/d4h/api/error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    # Public: Raised when the D4H API returns a non-2xx HTTP response.
+    #
+    # The message is built from the response body's "error" and "message"
+    # fields, joined with a colon.
+    #
+    # Examples
+    #
+    #   begin
+    #     client.equipment.show(id: 999_999)
+    #   rescue D4H::API::Error => e
+    #     e.message  # => "Not Found: Equipment not found"
+    #   end
+    class Error < StandardError
+    end
+
+    # Public: Raised for transient HTTP errors that are safe to retry.
+    #
+    # Triggered by 429 (rate limited) and 5xx (server error) responses.
+    # The Faraday retry middleware catches this exception and retries
+    # with exponential backoff.
+    #
+    # If all retries are exhausted the exception propagates to the caller,
+    # so it can still be rescued like any other D4H::API::Error.
+    class RetriableError < Error
+    end
+  end
+end

data/lib/d4h/api/model.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module D4H
+  module API
+    # Public: Base class for all D4H API response models.
+    #
+    # Wraps a JSON response hash in an OpenStruct so that attributes are
+    # accessible via dot-notation. Nested hashes and arrays are recursively
+    # converted, allowing deep attribute traversal.
+    #
+    # Subclasses (e.g. Member, Event, Equipment) are thin wrappers that
+    # exist primarily for type identification via `kind_of?`.
+    #
+    # Examples
+    #
+    #   model = D4H::API::Model.new({"id" => 1, "name" => "Alice"})
+    #   model.id    # => 1
+    #   model.name  # => "Alice"
+    #
+    #   # Nested data
+    #   model = D4H::API::Model.new({"brand" => {"title" => "Petzl"}})
+    #   model.brand.title  # => "Petzl"
+    #
+    #   # Raw JSON hash
+    #   model.to_json  # => {"id" => 1, "name" => "Alice"}
+    class Model < OpenStruct
+      # Public: Returns the original JSON hash that was used to build this model.
+      attr_reader :to_json
+
+      # Public: Initialize a Model from a JSON response hash.
+      #
+      # attributes - A Hash of key/value pairs from the API response.
+      def initialize(attributes)
+        super(to_ostruct(attributes))
+        @to_json = attributes
+      end
+
+      # Internal: Recursively convert a parsed JSON object into OpenStructs.
+      #
+      # obj - A Hash, Array, or scalar value from the parsed JSON.
+      #
+      # Returns an OpenStruct (for Hash), Array of converted values, or the
+      # original scalar.
+      def to_ostruct(obj)
+        if obj.is_a?(Hash)
+          OpenStruct.new(obj.map { |key, val| [key, to_ostruct(val)] }.to_h)
+        elsif obj.is_a?(Array)
+          obj.map { |o| to_ostruct(o) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/d4h/api/models/animal.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Animal < Model
+    end
+  end
+end

data/lib/d4h/api/models/animal_group.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class AnimalGroup < Model
+    end
+  end
+end

data/lib/d4h/api/models/animal_group_membership.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class AnimalGroupMembership < Model
+    end
+  end
+end

data/lib/d4h/api/models/animal_qualification.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class AnimalQualification < Model
+    end
+  end
+end

data/lib/d4h/api/models/attendance.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Attendance < Model
+    end
+  end
+end

data/lib/d4h/api/models/custom_field.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class CustomField < Model
+    end
+  end
+end

data/lib/d4h/api/models/custom_field_for_entity.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class CustomFieldForEntity < Model
+    end
+  end
+end

data/lib/d4h/api/models/customer_identifier.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class CustomerIdentifier < Model
+    end
+  end
+end

data/lib/d4h/api/models/d4h_module.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class D4hModule < Model
+    end
+  end
+end

data/lib/d4h/api/models/d4h_task.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class D4hTask < Model
+    end
+  end
+end

data/lib/d4h/api/models/document.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Document < Model
+    end
+  end
+end

data/lib/d4h/api/models/duty.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Duty < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Equipment < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_brand.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentBrand < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_category.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentCategory < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_fund.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentFund < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_inspection.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentInspection < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_inspection_result.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentInspectionResult < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_inspection_step.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentInspectionStep < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_inspection_step_result.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentInspectionStepResult < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_kind.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentKind < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_location.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentLocation < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_model.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentModel < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_retired_reason.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentRetiredReason < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_supplier.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentSupplier < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_supplier_ref.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentSupplierRef < Model
+    end
+  end
+end

data/lib/d4h/api/models/equipment_usage.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class EquipmentUsage < Model
+    end
+  end
+end

data/lib/d4h/api/models/event.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Event < Model
+    end
+  end
+end

data/lib/d4h/api/models/exercise.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module D4H
+  module API
+    class Exercise < Model
+    end
+  end
+end