trustid_sdk 0.2.0

data/lib/trustid_sdk/models/application_flexible_field_value.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module TrustID
+  # ApplicationFlexibleFieldValue
+  #
+  # Represents the value for an application-level custom field.
+  #
+  # Fields:
+  #   behaviour_flags_dup         - Integer: Behaviour flags for this field.
+  #   data_range_dup              - String: Duplicated data range information.
+  #   default_value_dup           - String: Duplicated default value.
+  #   document_container_id       - String: ID of the document container this value is assigned to.
+  #   field_order_index_dup       - Integer: Duplicated field order index.
+  #   field_value_date            - DateTime: Value if the field is a date/time.
+  #   field_value_decimal         - Decimal: Value if the field is a decimal.
+  #   field_value_int             - Integer: Value if the field is an integer.
+  #   field_value_string          - String: Value if the field is a string.
+  #   flexible_field_data_type_id_dup - Integer: Duplicated field type ID.
+  #   flexible_field_display_name_dup - String: Duplicated field display name.
+  #   flexible_field_id           - String: ID of the corresponding custom field attribute.
+  #   flexible_field_name_dup     - String: Duplicated field name.
+  #   flexible_field_version_id   - String: Version ID of the custom field attribute.
+  #   help_text_dup              - String: Duplicated help text.
+  #   mandatory_dup              - Boolean: Duplicated mandatory flag.
+  #   mandatory_if_value_list_or_dup - String: Conditions for when the field is mandatory.
+  #   template                    - Hash: Template for the field.
+  #   validation_status           - String: Fail, Warning, or Pass value when measured against validation criteria.
+  #
+  # The model exposes a `document_container` method to resolve the related container by ID.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ApplicationFlexibleFieldValue.html
+  class ApplicationFlexibleFieldValue < BaseModel
+    attribute :behaviour_flags_dup, :integer
+    attribute :data_range_dup, :string
+    attribute :default_value_dup, :string
+    attribute :document_container_id, :string
+    attribute :field_order_index_dup, :integer
+    attribute :field_value_date, :datetime
+    attribute :field_value_decimal, :decimal
+    attribute :field_value_int, :integer
+    attribute :field_value_string, :string
+    attribute :flexible_field_data_type_id_dup, :integer
+    attribute :flexible_field_display_name_dup, :string
+    attribute :flexible_field_id, :string
+    attribute :flexible_field_name_dup, :string
+    attribute :flexible_field_version_id, :string
+    attribute :help_text_dup, :string
+    attribute :mandatory_dup, :boolean
+    attribute :mandatory_if_value_list_or_dup, :string
+    attribute :template
+    attribute :validation_status, :string
+
+    def initialize(attributes = {})
+      # Normalize keys to handle API response format
+      attributes = normalize_keys(attributes)
+      super
+    end
+
+    # Only expose document_container as a related model, loaded on demand.
+    # Uses a block to define how to resolve the association, for maximum flexibility.
+    def document_container
+      return nil unless document_container_id
+
+      @document_container ||= TrustID::Services::Containers.find(document_container_id)
+    end
+
+    private
+
+    # Helper method to normalize keys to lowercase underscored symbols
+    def normalize_keys(hash)
+      result = {}
+      hash.each do |key, value|
+        key_str = key.to_s.underscore.downcase
+        result[key_str.to_sym] = value
+      end
+      result
+    end
+  end
+end

data/lib/trustid_sdk/models/base_model.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative '../concerns/attribute_resolution'
+require 'active_support'
+
+module TrustID
+  # Base model for all models in the TrustID SDK.
+  class BaseModel
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include AttributeResolution
+
+    attribute :response
+
+    def self.from_hash(hash)
+      attrs = normalize_keys(hash)
+      attrs = parse_dates(attrs)
+      attrs = filter_undefined_attributes(attrs)
+      attrs[:response] = hash
+      new(attrs)
+    end
+
+    class << self
+      private
+
+      def normalize_keys(hash)
+        hash.transform_keys do |key|
+          key.is_a?(String) ? key.underscore : key.to_s.underscore
+        end
+      end
+
+      def parse_dates(attrs)
+        attrs.transform_values do |value|
+          if value.is_a?(String) && value.match(%r{^/Date\((\d+)([+-]\d+)?\)/$})
+            ms = value.match(%r{^/Date\((\d+)([+-]\d+)?\)/$})[1].to_i
+            Time.at(ms / 1000.0).to_datetime
+          else
+            value
+          end
+        end
+      end
+
+      def filter_undefined_attributes(attrs)
+        failed_attributes = attrs.keys.reject { |key| attribute_names.include?(key.to_s) }
+        unless failed_attributes.empty?
+          warn "Warning: The following attributes are not defined in #{name}: #{failed_attributes.join(', ')}"
+          attrs = attrs.reject { |key| failed_attributes.include?(key) }
+        end
+        attrs
+      end
+    end
+  end
+end

data/lib/trustid_sdk/models/branch.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Branch
+  #
+  # Represents a branch or office location within the TrustID system.
+  #
+  # Fields:
+  #   id              - String: Unique identifier for the branch.
+  #   name            - String: Display name of the branch.
+  #   address         - String: Address of the branch.
+  #   created_at      - DateTime: When the branch was created (ISO8601).
+  #   updated_at      - DateTime: When the branch was last updated (ISO8601).
+  #   organisation_id - String: Reference to the parent organisation.
+  #   organisation    - Organisation: Parent organisation, resolved model (optional, loaded on demand).
+  #
+  # When initialized, the model will resolve the organisation if provided in the attributes.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/Branch.html
+  class Branch < BaseModel
+    attribute :id, :string
+    attribute :name, :string
+    attribute :address, :string
+    attribute :created_at, :datetime
+    attribute :updated_at, :datetime
+    attribute :organisation_id, :string
+    attr_reader :organisation
+
+    def initialize(attributes = {})
+      super
+      @organisation = resolve_model(attributes[:organisation], TrustID::Organisation)
+    end
+  end
+end

data/lib/trustid_sdk/models/callback_info.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TrustID
+  # CallbackInfo
+  #
+  # Represents metadata and state for a callback event in the TrustID system.
+  #
+  # Fields:
+  #   id           - String: Unique identifier for the callback event.
+  #   event_type   - String: Type of event triggering the callback.
+  #   status       - Integer: Status code (see CallbackState).
+  #   payload      - Hash/Object: Data sent with the callback.
+  #   created_at   - DateTime: When the callback was created.
+  #   processed_at - DateTime: When the callback was processed.
+  #   error_message- String: Optional, error details if processing failed.
+  #
+  # The model exposes a `status_name` method to resolve the status code to a human-readable name using CallbackState.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/CallbackInfo.html
+  class CallbackInfo < BaseModel
+    attribute :id, :string
+    attribute :event_type, :string
+    attribute :status, :integer
+    attribute :payload
+    attribute :created_at, :datetime
+    attribute :processed_at, :datetime
+    attribute :error_message, :string
+
+    def status_name
+      TrustID::CallbackState.name_for(status)
+    end
+  end
+end

data/lib/trustid_sdk/models/callback_state.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module TrustID
+  # CallbackState
+  #
+  # Enum representing the possible states for a callback event in the TrustID system.
+  #
+  # Enum values:
+  #   SCHEDULED         (1)  - A callback operation has been scheduled to be processed shortly.
+  #   PROCESSING        (2)  - A callback operation is currently being processed.
+  #   OPERATOR_ACTION   (3)  - Waiting for manual operator action.
+  #   READY_TO_DISPATCH (4)  - Ready to be dispatched back through the callback mechanism.
+  #   DISPATCHED        (5)  - Callback has been dispatched successfully.
+  #   UNABLE_TO_DISPATCH (6) - Unable to dispatch the callback operation.
+  #   WORKFLOW          (10) - Executing a workflow associated with this callback operation.
+  #   WORKFLOW_COMPLETE (11) - Workflow completed, no callback required.
+  #
+  # Use as: CallbackState::SCHEDULED, etc.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/CallbackState.html
+  class CallbackState
+    SCHEDULED         = 1
+    PROCESSING        = 2
+    OPERATOR_ACTION   = 3
+    READY_TO_DISPATCH = 4
+    DISPATCHED        = 5
+    UNABLE_TO_DISPATCH = 6
+    WORKFLOW          = 10
+    WORKFLOW_COMPLETE = 11
+
+    NAMES = {
+      SCHEDULED => 'Scheduled',
+      PROCESSING => 'Processing',
+      OPERATOR_ACTION => 'OperatorAction',
+      READY_TO_DISPATCH => 'ReadyToDispatch',
+      DISPATCHED => 'Dispatched',
+      UNABLE_TO_DISPATCH => 'UnableToDispatch',
+      WORKFLOW => 'Workflow',
+      WORKFLOW_COMPLETE => 'WorkflowComplete'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/chargeable_status.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TrustID
+  # ChargeableStatus
+  #
+  # Enum representing the charge status for scans with a given document type.
+  #
+  # Enum values:
+  #   NO_CHARGE          (0) - Don’t charge for scans with this document type.
+  #   CHARGE             (1) - Charge for scans with this document type.
+  #   CHARGE_IF_REVIEWED (2) - Charge for scans with this document type if the scan has been manually reviewed.
+  #
+  # Use as: ChargeableStatus::NO_CHARGE, etc.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ChargeableStatus.html
+  class ChargeableStatus
+    NO_CHARGE          = 0
+    CHARGE             = 1
+    CHARGE_IF_REVIEWED = 2
+
+    NAMES = {
+      NO_CHARGE => 'NoCharge',
+      CHARGE => 'Charge',
+      CHARGE_IF_REVIEWED => 'ChargeIfReviewed'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/configuration.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require_relative '../concerns/attribute_resolution'
+
+module TrustID
+  # Configuration
+  #
+  # Represents a set of configuration key/value pairs from the TrustID API.
+  #
+  # Fields:
+  #   config_map - Hash: Internal map of configuration keys to values (as returned by the API).
+  #
+  # Example API response:
+  #   "Configuration": [
+  #     { "Key": "support.pagination", "Value": "False" },
+  #     ...
+  #   ]
+  #
+  # Provides boolean and integer accessors for common configuration keys, and generic access via [].
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/Configuration.html
+  class Configuration < BaseModel
+    attr_reader :config_map
+
+    def initialize(config_array)
+      @config_map = Array(config_array).each_with_object({}) do |item, map|
+        map[item['Key'] || item[:Key]] = item['Value'] || item[:Value]
+      end
+    end
+
+    # Accessors for common configuration keys (see API docs)
+    def support_pagination?
+      config_bool('support.pagination')
+    end
+
+    def ui_photo_matches_required_enabled?
+      config_bool('ui.photomatchesrequired.enabled')
+    end
+
+    def ui_person_not_seen_required_enabled?
+      config_bool('ui.personnotseenrequired.enabled')
+    end
+
+    def ui_multiple_documents_per_application_disabled?
+      config_bool('ui.multiple_documents_per_application.disabled')
+    end
+
+    def ui_driving_licence_side2_mandatory_enabled?
+      config_bool('ui.drivinglicenceside2.mandatory.enabled')
+    end
+
+    def ui_id_card_side2_mandatory_enabled?
+      config_bool('ui.idcardside2.mandatory.enabled')
+    end
+
+    def service_system_type
+      config_int('servicesystemtype')
+    end
+
+    # Generic access
+    def [](key)
+      @config_map[key]
+    end
+
+    private
+
+    def config_bool(key)
+      @config_map[key].to_s.downcase == 'true'
+    end
+
+    def config_int(key)
+      Integer(@config_map[key])
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/trustid_sdk/models/container.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative 'access_lock'
+require_relative 'application_flexible_field_list'
+require_relative 'branch'
+require_relative 'dbs_check_initiation'
+require_relative 'document'
+require_relative 'document_container_field'
+require_relative 'document_container_validation'
+require_relative 'document_container_validation_outcome'
+require_relative 'document_source'
+require_relative 'document_storage_type'
+require_relative 'image'
+require_relative 'liveness_result_type'
+require_relative 'overall_status'
+require_relative 'referral_history_record'
+require_relative 'referral_type'
+require_relative 'review_application_state'
+require_relative 'user_reference'
+require_relative 'workflow_type'
+require_relative 'base_model'
+
+module TrustID
+  # Container
+  #
+  # Represents a document container within the TrustID system, holding documents and related metadata.
+  # The model uses HasNestedModels to handle nested data structures with proper type conversion.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/Container.html
+  class Container < BaseModel
+    include HasNestedModels
+
+    # Define nested models with their key variants (now inferred automatically)
+    nested_model :documents, Document, array: true
+
+    nested_model :applicant_photo_image, Image
+
+    nested_model :document_container_field_list, DocumentContainerField, array: true
+
+    nested_model :referred_from, UserReference
+
+    nested_model :dbs_check_initiation, DbsCheckInitiation
+
+    nested_model :access_lock, AccessLock
+
+    nested_model :referral_history, ReferralHistoryRecord, array: true
+
+    nested_model :application_flexible_field_list, ApplicationFlexibleFieldList, array: true
+
+    nested_model :document_container_validation_list, DocumentContainerValidation, array: true
+
+    # Define all attributes
+    attribute :access_lock
+    attribute :applicant_photo_image
+    attribute :application_flexible_field_list, array: true
+    attribute :application_read, :boolean
+    attribute :address_history, array: true
+    attribute :branch_id, :string
+    attribute :branch_name, :string
+    attribute :client_app_id, :integer
+    attribute :created_at, :datetime
+    attribute :dbs_check_initiation
+    attribute :dbs_status, :string
+    attribute :document_container_field_list, array: true
+    attribute :document_container_validation_list, array: true
+    attribute :document_source, :integer
+    attribute :document_storage_type, :integer
+    attribute :documents, array: true
+    attribute :entity_id, :string
+    attribute :fullname, :string
+    attribute :id, :string
+    attribute :is_full_check, :boolean
+    attribute :journey_id, :string
+    attribute :liveness_test_count, :integer
+    attribute :liveness_test_result, :integer
+    attribute :liveness_test_result_auto, :integer
+    attribute :organisation_id, :string
+    attribute :organisation_name, :string
+    attribute :overall_status, :integer
+    attribute :process_expiry_time_utc, :datetime
+    attribute :referral_history, array: true
+    attribute :referral_type, :integer
+    attribute :referred, :boolean
+    attribute :referred_at, :datetime
+    attribute :referred_from
+    attribute :review_application_instigating_user, :string
+    attribute :review_application_state, :integer
+    attribute :scanned_by_user, :string
+    attribute :synchronised, :boolean
+    attribute :system_id, :string
+    attribute :total_alerts, :integer
+    attribute :tta_import, :boolean
+    attribute :updated_at, :datetime
+    attribute :user_id, :string
+    attribute :vpe_device_id, :string
+    attribute :vpe_name, :string
+    attribute :vpe_type, :integer
+    attribute :workflow_type, :integer
+
+    DocumentStorageType::NAMES.each do |code, name|
+      define_method("document_storage_#{name.underscore}?") do
+        document_storage_type == code
+      end
+    end
+
+    def document_storage_type_name
+      DocumentStorageType.name_for(document_storage_type)
+    end
+
+    LivenessResultType::NAMES.each do |code, name|
+      define_method("liveness_result_#{name.underscore}?") do
+        liveness_test_result == code
+      end
+    end
+
+    def liveness_test_result_name
+      LivenessResultType.name_for(liveness_test_result)
+    end
+
+    OverallStatus::NAMES.each do |code, name|
+      define_method("overall_status_#{name.underscore}?") do
+        overall_status == code
+      end
+    end
+
+    def overall_status_name
+      OverallStatus.name_for(overall_status)
+    end
+
+    ReferralType::NAMES.each do |code, name|
+      define_method("referral_#{name.underscore}?") do
+        referral_type == code
+      end
+    end
+
+    def referral_type_name
+      ReferralType.name_for(referral_type)
+    end
+
+    WorkflowType::NAMES.each do |code, name|
+      define_method("workflow_#{name.underscore}?") do
+        workflow_type == code
+      end
+    end
+
+    def workflow_type_name
+      WorkflowType.name_for(workflow_type)
+    end
+
+    def overall_status_ok?
+      overall_status_no_alert? || overall_status_resolved?
+    end
+    alias ok? overall_status_ok?
+
+    def self.find(container_id)
+      TrustID::Services::Containers.retrieve(container_id: container_id)
+    end
+
+    # Convenience methods for easier access to container data
+
+    # Get the first document (most common use case)
+    #
+    # @return [Document, nil] The first document if available, nil otherwise
+    def first_document
+      documents&.first
+    end
+
+    # Find a document by document ID
+    #
+    # @param document_id [String] The document ID to find
+    # @return [Document, nil] The document if found, nil otherwise
+    def document_by_id(document_id)
+      return nil unless documents.is_a?(Array)
+
+      documents.find { |doc| doc.document_id == document_id.to_s }
+    end
+
+    # Find documents by document type
+    #
+    # @param document_type [Integer] The document type code
+    # @return [Array<Document>] Array of documents of the specified type
+    def documents_by_type(document_type)
+      return [] unless documents.is_a?(Array)
+
+      documents.select { |doc| doc.document_type == document_type }
+    end
+
+    # Find a container validation by name (case-insensitive)
+    #
+    # @param validation_name [String] The name of the validation to find
+    # @return [DocumentContainerValidation, nil] The container validation if found, nil otherwise
+    def validation_by_name(validation_name)
+      return nil unless document_container_validation_list.is_a?(Array)
+
+      document_container_validation_list.find { |v| v.name&.downcase == validation_name.to_s.downcase }
+    end
+
+    # Get all passed container validations
+    #
+    # @return [Array<DocumentContainerValidation>] Array of passed validations
+    def passed_validations
+      return [] unless document_container_validation_list.is_a?(Array)
+
+      document_container_validation_list.select do |v|
+        v.validation_outcome == DocumentContainerValidationOutcome::PASSED
+      end
+    end
+
+    # Get all failed container validations (excluding passed and unknown)
+    #
+    # @return [Array<DocumentContainerValidation>] Array of failed validations
+    def failed_validations
+      return [] unless document_container_validation_list.is_a?(Array)
+
+      document_container_validation_list.reject do |v|
+        [DocumentContainerValidationOutcome::PASSED,
+         DocumentContainerValidationOutcome::UNKNOWN].include?(v.validation_outcome)
+      end
+    end
+
+    # Check if all container validations passed
+    #
+    # @return [Boolean] True if all validations passed, false otherwise
+    def all_validations_passed?
+      return true unless document_container_validation_list.is_a?(Array)
+
+      document_container_validation_list.all? do |v|
+        [DocumentContainerValidationOutcome::PASSED,
+         DocumentContainerValidationOutcome::UNKNOWN].include?(v.validation_outcome)
+      end
+    end
+
+    # Get a container field by name (case-insensitive)
+    #
+    # @param field_name [String] The name of the field to find
+    # @return [DocumentContainerField, nil] The container field if found, nil otherwise
+    def field_by_name(field_name)
+      return nil unless document_container_field_list.is_a?(Array)
+
+      document_container_field_list.find { |f| f.name&.downcase == field_name.to_s.downcase }
+    end
+
+    # Get the value of a container field by name
+    #
+    # @param field_name [String] The name of the field
+    # @return [String, DateTime, nil] The field value (string or date), or nil if not found
+    def field_value(field_name)
+      field = field_by_name(field_name)
+      return nil unless field
+
+      field.field_value_string || field.field_value_date
+    end
+  end
+end

data/lib/trustid_sdk/models/custom_field.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TrustID
+  # CustomField
+  #
+  # Represents a custom field attached to a document or application in TrustID.
+  #
+  # Fields:
+  #   display_name  - String: Label for the field.
+  #   help          - String: Help text for the field.
+  #   index         - Integer: Order/index of the field.
+  #   property_name - String: Internal property name.
+  #   required      - Boolean: Whether the field is required.
+  #   value         - String: The field value.
+  #   values        - Array<String>: Allowed values if the field is an enum.
+  #
+  # Not all attributes may be present for every custom field; structure is flexible.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/CustomField.html
+  class CustomField < BaseModel
+    attribute :display_name, :string
+    attribute :help, :string
+    attribute :index, :integer
+    attribute :property_name, :string
+    attribute :required, :boolean
+    attribute :value, :string
+    attribute :values, default: []
+  end
+end

data/lib/trustid_sdk/models/dbs_check_initiation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TrustID
+  # DbsCheckInitiation
+  #
+  # Represents the DBS (Disclosure and Barring Service) check initiation details.
+  #
+  # Fields:
+  #   state - Integer: The state of the DBS check initiation.
+  #
+  class DbsCheckInitiation < BaseModel
+    attribute :state, :integer
+  end
+end