trustid_sdk 0.2.0

data/lib/trustid_sdk/models/document.rb

@@ -0,0 +1,646 @@
+# frozen_string_literal: true
+
+require_relative 'image'
+require_relative 'document_type'
+require_relative 'document_status'
+require_relative 'document_field'
+require_relative 'document_validation'
+require_relative 'document_validation_result'
+require_relative 'external_service_data'
+require_relative 'document_feedback'
+require_relative 'document_configuration'
+require_relative 'kdb_country'
+require_relative 'kdb_document_sub_type'
+
+module TrustID
+  # Document
+  #
+  # Represents a document and its metadata in the TrustID system (TrustID API).
+  #
+  # Fields:
+  #   aspect_ratio                  - Float: Aspect ratio of the document image.
+  #   audited                       - Boolean: Whether the document has been audited.
+  #   audited_by_user               - String: User who audited the document.
+  #   auditor_message               - String: Message from the auditor.
+  #   auditor_status                - Integer: Auditor status (see DocumentStatus).
+  #   blacklisted                   - Boolean: Whether the document is blacklisted.
+  #   blacklisted_at                - DateTime: When the document was blacklisted.
+  #   branch_name                   - String: Name of the branch.
+  #   compatibility_document_sub_type_code - String: Compatibility document sub-type code.
+  #   compatibility_document_type_code - String: Compatibility document type code.
+  #   compatibility_issuing_country_code - String: Compatibility issuing country code.
+  #   compatibility_nationality_code - String: Compatibility nationality code.
+  #   contactless_chip_read_state   - Integer: Contactless chip read state.
+  #   container_id                  - String: ID of the container this document belongs to.
+  #   continued_manually            - Boolean: Whether the document was continued manually.
+  #   created_at                    - DateTime: When the document was created.
+  #   custom_field_dictionary       - Array<{ key: String, value: CustomField }>: Custom fields.
+  #   custom_field_keys             - Array<String>: Keys for custom fields.
+  #   detected_orientation          - Integer: Detected image orientation (see ImageOrientation).
+  #   document_completed            - Boolean: Whether the document is completed.
+  #   document_configuration        - DocumentConfiguration: Document configuration.
+  #   document_fields               - Array<DocumentField>: Document fields.
+  #   document_id                   - String: Document ID.
+  #   document_name                 - String: Name of the document.
+  #   document_results_summary      - Array<DocumentFeedback>: Results summary.
+  #   document_sub_type             - Integer: Document sub-type (see KDBDocumentSubType).
+  #   document_type                 - Integer: Document type (see DocumentType).
+  #   document_validations          - Array<DocumentValidation>: Document validations.
+  #   document_version              - String: Version of the document.
+  #   driving_licence_category      - String: Driving licence category.
+  #   editable                      - Boolean: Whether the document is editable.
+  #   expiry_notification           - Boolean: Expiry notification flag.
+  #   external_services             - Array<ExternalServiceData>: External services data.
+  #   external_services_queried     - Boolean: Whether external services were queried.
+  #   feedback_face                 - Integer: Feedback face.
+  #   feedback_features             - Array<DocumentFeatureFeedback>: Feedback features.
+  #   feedback_has_mrz              - Boolean: Whether feedback has MRZ.
+  #   feedback_person_matches       - Integer: Number of person matches in feedback.
+  #   feedback_rfid_image_matches   - Boolean or nil: Whether RFID image matches.
+  #   feedback_uv                   - Integer: Feedback UV.
+  #   feedback_uv_pattern           - Integer: Feedback UV pattern.
+  #   font                          - String: Font.
+  #   font_alignment                - Integer: Font alignment.
+  #   font_height                   - Integer: Font height.
+  #   forwarded                     - Boolean: Forwarded flag.
+  #   general_document_properties   - Array<DocumentFeedback>: General document properties.
+  #   has_error                     - Boolean: Whether the document has an error.
+  #   high_risk_country             - Boolean: High risk country flag.
+  #   images                        - Array<Image>: Associated images.
+  #   issuing_authority             - String: Issuing authority.
+  #   issuing_country               - Integer: Issuing country (see KDBCountry).
+  #   kdb                           - Boolean: KDB flag.
+  #   locked                        - Boolean: Locked flag.
+  #   mandatory_document_fields_flag - Integer: Mandatory document fields flag.
+  #   mrz_corrected                 - Boolean: Whether MRZ was corrected.
+  #   mrz_correction_provided       - Boolean: Whether MRZ correction was provided.
+  #   max_age_failed                - Integer or nil: Max age failed value.
+  #   min_age_failed                - Integer or nil: Min age failed value.
+  #   missing_fields_properties     - Array<DocumentFeedback>: Missing fields properties.
+  #   mrz                           - String: MRZ string.
+  #   mrz_character_count           - Integer: MRZ character count.
+  #   mrz_image_type                - Integer: MRZ image type (see ImageType).
+  #   mrz_line_count                - Integer: MRZ line count.
+  #   mrz_same_length               - Boolean: Whether MRZ lines are the same length.
+  #   mrz_validation_properties     - Array<DocumentFeedback>: MRZ validation properties.
+  #   nationality                   - Integer: Nationality (see KDBCountry).
+  #   no_initial_face_image         - Boolean: No initial face image flag.
+  #   notes                         - String: Notes.
+  #   ocr_data_applied              - Boolean: Whether OCR data was applied.
+  #   ocr_field_data                - Array<OcrFieldData>: OCR field data.
+  #   ocr_type                      - Integer: OCR type.
+  #   operator_message              - String: Operator message.
+  #   operator_status               - Integer: Operator status (see DocumentStatus).
+  #   optional_document_fields_flag  - Integer: Optional document fields flag.
+  #   original_mrz                  - String: Original MRZ string.
+  #   partially_recognised          - Boolean: Partially recognised flag.
+  #   reading_attempts_count        - Integer: Reading attempts count.
+  #   rfid_failed                   - Boolean: RFID failed flag.
+  #   rfid_mrz                      - String: RFID MRZ string.
+  #   rule_denied                   - Boolean: Rule denied flag.
+  #   scan_counter                  - Integer: Scan counter.
+  #   scanned_at                    - DateTime: When the document was scanned.
+  #   scanner_type                  - String: Scanner type.
+  #   seen_before_document_container_id - String: Seen before document container ID.
+  #   seen_before_document_id       - String: Seen before document ID.
+  #   successfully_read             - Boolean: Successfully read flag.
+  #   supporting_document_name      - String: Supporting document name.
+  #   system_id                     - String: System ID.
+  #   unrecognised                  - Boolean: Unrecognised flag.
+  #   updated_at                    - DateTime: When the document was last updated.
+  #   valid_from                    - Date: Valid from date.
+  #   valid_length                  - Boolean: Valid length flag.
+  #   vpe_device_id                 - String: VPE device ID.
+  #   vpe_name                      - String: VPE name.
+  #   wizard_completed              - Boolean: Wizard completed flag.
+  #   workflow_flags                - Integer: Workflow flags.
+  #
+  # The model resolves nested/related models for images and custom fields, and provides full access to all
+  # TrustID document metadata.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/Document.html
+  class Document < BaseModel # rubocop:disable Metrics/ClassLength
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    # Attributes (from TrustID API):
+    # - aspect_ratio: Float
+    # - audited: Boolean
+    # - audited_by_user: String
+    # - auditor_message: String
+    # - auditor_status: Integer (see DocumentStatus)
+    # - blacklisted: Boolean
+    # - blacklisted_at: String (ISO8601 datetime)
+    # - branch_name: String
+    # - compatibility_document_sub_type_code: String
+    # - compatibility_document_type_code: String
+    # - compatibility_issuing_country_code: String
+    # - compatibility_nationality_code: String
+    # - contactless_chip_read_state: Integer
+    # - container_id: String
+    # - continued_manually: Boolean
+    # - created_at: String (ISO8601 datetime)
+    # - custom_field_dictionary: Array of { key: String, value: CustomField }
+    # - custom_field_keys: Array of String
+    # - detected_orientation: Integer (see ImageOrientation)
+    # - document_completed: Boolean
+    # - document_configuration: DocumentConfiguration
+    # - document_fields: Array of DocumentField
+    # - document_id: String
+    # - document_name: String
+    # - document_results_summary: Array of DocumentFeedback
+    # - document_sub_type: Integer (see KDBDocumentSubType)
+    # - document_type: Integer (see DocumentType)
+    # - document_validations: Array of DocumentValidation
+    # - document_version: String
+    # - driving_licence_category: String
+    # - editable: Boolean
+    # - expiry_notification: Boolean
+    # - external_services: Array of ExternalServiceData
+    # - external_services_queried: Boolean
+    # - feedback_face: Integer
+    # - feedback_features: Array of DocumentFeatureFeedback
+    # - feedback_has_mrz: Boolean
+    # - feedback_person_matches: Integer
+    # - feedback_rfid_image_matches: Boolean or nil
+    # - feedback_uv: Integer
+    # - feedback_uv_pattern: Integer
+    # - font: String
+    # - font_alignment: Integer
+    # - font_height: Integer
+    # - forwarded: Boolean
+    # - general_document_properties: Array of DocumentFeedback
+    # - has_error: Boolean
+    # - high_risk_country: Boolean
+    # - images: Array of Image
+    # - issuing_authority: String
+    # - issuing_country: Integer (see KDBCountry)
+    # - kdb: Boolean
+    # - locked: Boolean
+    # - mandatory_document_fields_flag: Integer
+    # - mrz_corrected: Boolean
+    # - mrz_correction_provided: Boolean
+    # - max_age_failed: Integer or nil
+    # - min_age_failed: Integer or nil
+    # - missing_fields_properties: Array of DocumentFeedback
+    # - mrz: String
+    # - mrz_character_count: Integer
+    # - mrz_image_type: Integer (see ImageType)
+    # - mrz_line_count: Integer
+    # - mrz_same_length: Boolean
+    # - mrz_validation_properties: Array of DocumentFeedback
+    # - nationality: Integer (see KDBCountry)
+    # - no_initial_face_image: Boolean
+    # - notes: String
+    # - ocr_data_applied: Boolean
+    # - ocr_field_data: Array of OcrFieldData
+    # - ocr_type: Integer
+    # - operator_message: String
+    # - operator_status: Integer (see DocumentStatus)
+    # - optional_document_fields_flag: Integer
+    # - original_mrz: String
+    # - partially_recognised: Boolean
+    # - reading_attempts_count: Integer
+    # - rfid_failed: Boolean
+    # - rfid_mrz: String
+    # - rule_denied: Boolean
+    # - scan_counter: Integer
+    # - scanned_at: String (ISO8601 datetime)
+    # - scanner_type: String
+    # - seen_before_document_container_id: String
+    # - seen_before_document_id: String
+    # - successfully_read: Boolean
+    # - supporting_document_name: String
+    # - system_id: String
+    # - unrecognised: Boolean
+    # - updated_at: String (ISO8601 datetime)
+    # - valid_from: String (ISO8601 date)
+    # - valid_length: Boolean
+    # - vpe_device_id: String
+    # - vpe_name: String
+    # - wizard_completed: Boolean
+    # - workflow_flags: Integer
+    #
+
+    attribute :aspect_ratio, :float
+    attribute :audited, :boolean
+    attribute :audited_by_user, :string
+    attribute :auditor_message, :string
+    attribute :auditor_status, :integer
+    attribute :blacklisted, :boolean
+    attribute :blacklisted_at, :datetime
+    attribute :branch_name, :string
+    attribute :compatibility_document_sub_type_code, :string
+    attribute :compatibility_document_type_code, :string
+    attribute :compatibility_issuing_country_code, :string
+    attribute :compatibility_nationality_code, :string
+    attribute :contactless_chip_read_state, :integer
+    attribute :container_id, :string
+    attribute :continued_manually, :boolean
+    attribute :created_at, :datetime
+    attribute :custom_field_dictionary
+    attribute :custom_field_keys
+    attribute :detected_orientation, :integer
+    attribute :document_completed, :boolean
+    attribute :document_configuration
+    attribute :document_fields
+    attribute :document_id, :string
+    # NOTE: 'id' is a Container-level attribute, not a Document attribute.
+    # It may appear in some API responses but is ignored here.
+    attribute :id, :string
+    attribute :document_name, :string
+    attribute :document_results_summary
+    attribute :document_sub_type
+    attribute :document_type, :integer
+    attribute :document_validations
+    attribute :document_version, :string
+    attribute :driving_licence_category, :string
+    attribute :editable, :boolean
+    attribute :expiry_notification, :boolean
+    attribute :external_services
+    attribute :external_services_queried, :boolean
+    attribute :feedback_face, :integer
+    attribute :feedback_features
+    attribute :feedback_has_mrz, :boolean
+    attribute :feedback_person_matches, :integer
+    attribute :feedback_rfid_image_matches
+    attribute :feedback_uv, :integer
+    attribute :feedback_uv_pattern, :integer
+    attribute :font, :string
+    attribute :font_alignment, :integer
+    attribute :font_height, :integer
+    attribute :forwarded, :boolean
+    attribute :general_document_properties
+    attribute :has_error, :boolean
+    attribute :high_risk_country, :boolean
+    attribute :issuing_authority, :string
+    attribute :issuing_country
+    attribute :kdb, :boolean
+    attribute :locked, :boolean
+    attribute :mandatory_document_fields_flag, :integer
+    attribute :mrz_corrected, :boolean
+    attribute :mrz_correction_provided, :boolean
+    attribute :max_age_failed, :integer
+    attribute :min_age_failed, :integer
+    attribute :missing_fields_properties
+    attribute :mrz, :string
+    attribute :mrz_character_count, :integer
+    attribute :mrz_image_type, :integer
+    attribute :mrz_line_count, :integer
+    attribute :mrz_same_length, :boolean
+    attribute :mrz_validation_properties
+    attribute :nationality, :integer
+    attribute :no_initial_face_image, :boolean
+    attribute :notes, :string
+    attribute :ocr_data_applied, :boolean
+    attribute :ocr_field_data
+    attribute :ocr_type, :integer
+    attribute :operator_message, :string
+    attribute :operator_status, :integer
+    attribute :optional_document_fields_flag, :integer
+    attribute :original_mrz, :string
+    attribute :partially_recognised, :boolean
+    attribute :reading_attempts_count, :integer
+    attribute :rfid_failed, :boolean
+    attribute :rfid_mrz, :string
+    attribute :rule_denied, :boolean
+    attribute :scan_counter, :integer
+    attribute :scanned_at, :datetime
+    attribute :scanner_type, :string
+    attribute :seen_before_document_container_id, :string
+    attribute :seen_before_document_id, :string
+    attribute :successfully_read, :boolean
+    attribute :supporting_document_name, :string
+    attribute :system_id, :string
+    attribute :unrecognised, :boolean
+    attribute :updated_at, :datetime
+    attribute :valid_from, :date
+    attribute :valid_length, :boolean
+    attribute :vpe_device_id, :string
+    attribute :vpe_name, :string
+    attribute :wizard_completed, :boolean
+    attribute :workflow_flags, :integer
+    attribute :is_biometric, :boolean
+    attribute :images, array: true
+
+    # Store the images separately since it's a complex nested structure
+    attr_reader :images, :document_fields, :document_validations, :external_services, :document_configuration,
+                :general_document_properties, :document_results_summary, :mrz_validation_properties,
+                :missing_fields_properties
+
+    # Initialize method to properly handle nested structures
+    def initialize(attrs = {})
+      # Normalize input hash - convert all keys to strings for consistent lookup
+      attrs = attrs.transform_keys(&:to_s) if attrs.is_a?(Hash)
+
+      # Initialize the model with all attributes (including nested ones)
+      super
+
+      # Convert nested structures from hashes to model instances after initialization
+      convert_nested_models
+    end
+
+    # Convert nested model data from hashes to proper model instances
+    def convert_nested_models
+      convert_array_attribute(:images, @images)
+      convert_array_attribute(:document_fields, document_fields)
+      convert_array_attribute(:document_validations, document_validations)
+      convert_array_attribute(:external_services, external_services)
+      convert_array_attribute(:document_results_summary, document_results_summary)
+      convert_array_attribute(:general_document_properties, general_document_properties)
+      convert_array_attribute(:mrz_validation_properties, mrz_validation_properties)
+      convert_array_attribute(:missing_fields_properties, missing_fields_properties)
+      convert_hash_attribute(:nationality, nationality)
+      convert_hash_attribute(:issuing_country, issuing_country)
+      convert_hash_attribute(:document_sub_type, document_sub_type)
+      convert_hash_attribute(:document_configuration, document_configuration)
+    end
+
+    # Convert an array attribute if it contains hashes
+    def convert_array_attribute(attr_name, value)
+      return unless value.is_a?(Array) && value.first.is_a?(Hash)
+
+      send("#{attr_name}=", value)
+    end
+
+    # Convert a hash attribute to a model instance
+    def convert_hash_attribute(attr_name, value)
+      return unless value.is_a?(Hash)
+
+      send("#{attr_name}=", value)
+    end
+
+    # Set the images array with proper type conversion
+    def images=(images_data)
+      return unless images_data
+
+      @images = images_data.map do |image_data|
+        image_data.is_a?(TrustID::Image) ? image_data : TrustID::Image.from_hash(image_data)
+      end
+    end
+
+    # Set document_fields with proper type conversion
+    def document_fields=(fields_data)
+      return unless fields_data
+
+      # Handle both array of hashes and already converted models
+      @document_fields = Array(fields_data).map do |field_data|
+        if field_data.is_a?(Hash)
+          TrustID::DocumentField.from_hash(field_data)
+        else
+          field_data
+        end
+      end
+    end
+
+    # Set document_validations with proper type conversion
+    def document_validations=(validations_data)
+      return unless validations_data
+
+      # Handle both array of hashes and already converted models
+      @document_validations = Array(validations_data).map do |validation_data|
+        if validation_data.is_a?(Hash)
+          TrustID::DocumentValidation.from_hash(validation_data)
+        else
+          validation_data
+        end
+      end
+    end
+
+    # Set external_services with proper type conversion
+    def external_services=(services_data)
+      return unless services_data
+
+      # Handle both array of hashes and already converted models
+      @external_services = Array(services_data).map do |service_data|
+        if service_data.is_a?(Hash)
+          TrustID::ExternalServiceData.from_hash(service_data)
+        else
+          service_data
+        end
+      end
+    end
+
+    # Set document_results_summary with proper type conversion
+    def document_results_summary=(summary_data)
+      return unless summary_data
+
+      @document_results_summary = summary_data.map do |item_data|
+        item_data.is_a?(TrustID::DocumentFeedback) ? item_data : TrustID::DocumentFeedback.from_hash(item_data)
+      end
+    end
+
+    # Set general_document_properties with proper type conversion
+    def general_document_properties=(properties_data)
+      return unless properties_data
+
+      @general_document_properties = properties_data.map do |item_data|
+        item_data.is_a?(TrustID::DocumentFeedback) ? item_data : TrustID::DocumentFeedback.from_hash(item_data)
+      end
+    end
+
+    # Set mrz_validation_properties with proper type conversion
+    def mrz_validation_properties=(properties_data)
+      return unless properties_data
+
+      @mrz_validation_properties = properties_data.map do |item_data|
+        item_data.is_a?(TrustID::DocumentFeedback) ? item_data : TrustID::DocumentFeedback.from_hash(item_data)
+      end
+    end
+
+    # Set missing_fields_properties with proper type conversion
+    def missing_fields_properties=(properties_data)
+      return unless properties_data
+
+      @missing_fields_properties = properties_data.map do |item_data|
+        item_data.is_a?(TrustID::DocumentFeedback) ? item_data : TrustID::DocumentFeedback.from_hash(item_data)
+      end
+    end
+
+    # Set nationality as KDBCountry object
+    def nationality=(country_data)
+      return unless country_data
+
+      @nationality = country_data.is_a?(TrustID::KDBCountry) ? country_data : TrustID::KDBCountry.from_hash(country_data)
+    end
+
+    # Set issuing_country as KDBCountry object
+    def issuing_country=(country_data)
+      return unless country_data
+
+      @issuing_country = country_data.is_a?(TrustID::KDBCountry) ? country_data : TrustID::KDBCountry.from_hash(country_data)
+    end
+
+    # Set document_sub_type as KDBDocumentSubType object
+    def document_sub_type=(sub_type_data)
+      return unless sub_type_data
+
+      @document_sub_type = sub_type_data.is_a?(TrustID::KDBDocumentSubType) ? sub_type_data : TrustID::KDBDocumentSubType.from_hash(sub_type_data)
+    end
+
+    # Set document_version (keeping as string for now, but could be an object)
+    attr_writer :document_version
+
+    # Set document_configuration with proper type conversion
+    def document_configuration=(config_data)
+      return unless config_data
+
+      @document_configuration = config_data.is_a?(TrustID::DocumentConfiguration) ? config_data : TrustID::DocumentConfiguration.from_hash(config_data)
+    end
+
+    DocumentType::NAMES.each do |code, name|
+      define_method("document_type_#{name.underscore}?") do
+        document_type == code
+      end
+    end
+
+    def document_type_name
+      DocumentType.name_for(document_type)
+    end
+
+    DocumentStatus::NAMES.each do |code, name|
+      define_method("auditor_status_#{name.underscore}?") do
+        auditor_status == code
+      end
+    end
+
+    def auditor_status_name
+      DocumentStatus.name_for(auditor_status)
+    end
+
+    # Convenience methods for easier access to document data
+
+    # Find a document field by name (case-insensitive)
+    #
+    # @param field_name [String] The name of the field to find (e.g., "VI Firstname", "VIZ Surname")
+    # @return [DocumentField, nil] The document field if found, nil otherwise
+    def field_by_name(field_name)
+      return nil unless document_fields.is_a?(Array)
+
+      document_fields.find { |f| f.name&.downcase == field_name.to_s.downcase }
+    end
+
+    # Get the value of a document 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
+
+    # Find a document validation by name (case-insensitive)
+    #
+    # @param validation_name [String] The name of the validation to find
+    # @return [DocumentValidation, nil] The document validation if found, nil otherwise
+    def validation_by_name(validation_name)
+      return nil unless document_validations.is_a?(Array)
+
+      document_validations.find { |v| v.name&.downcase == validation_name.to_s.downcase }
+    end
+
+    # Get all passed validations
+    #
+    # @return [Array<DocumentValidation>] Array of passed validations
+    def passed_validations
+      return [] unless document_validations.is_a?(Array)
+
+      document_validations.select { |v| v.result == DocumentValidationResult::PASSED }
+    end
+
+    # Get all failed validations (excluding passed and unknown)
+    #
+    # @return [Array<DocumentValidation>] Array of failed validations
+    def failed_validations
+      return [] unless document_validations.is_a?(Array)
+
+      document_validations.reject do |v|
+        [DocumentValidationResult::PASSED, DocumentValidationResult::UNKNOWN].include?(v.result)
+      end
+    end
+
+    # Check if all validations passed
+    #
+    # @return [Boolean] True if all validations passed, false otherwise
+    def all_validations_passed?
+      return true unless document_validations.is_a?(Array)
+
+      document_validations.all? do |v|
+        [DocumentValidationResult::PASSED, DocumentValidationResult::UNKNOWN].include?(v.result)
+      end
+    end
+
+    # Find an external service by name (case-insensitive)
+    #
+    # @param service_name [String] The name of the external service
+    # @return [ExternalServiceData, nil] The external service if found, nil otherwise
+    def external_service_by_name(service_name)
+      return nil unless external_services.is_a?(Array)
+
+      external_services.find { |s| s.name&.downcase == service_name.to_s.downcase }
+    end
+
+    # Get a summary result by name from document_results_summary
+    #
+    # @param summary_name [String] The name of the summary result
+    # @return [DocumentFeedback, nil] The summary result if found, nil otherwise
+    def summary_result_by_name(summary_name)
+      return nil unless document_results_summary.is_a?(Array)
+
+      document_results_summary.find { |s| s.name&.downcase == summary_name.to_s.downcase }
+    end
+
+    # Check if a summary result passed
+    #
+    # @param summary_name [String] The name of the summary result
+    # @return [Boolean, nil] True if passed, false if failed, nil if not found or unknown
+    def summary_result_passed?(summary_name)
+      result = summary_result_by_name(summary_name)
+      result&.value == true
+    end
+
+    # Get nationality name (from KDBCountry object if available)
+    #
+    # @return [String, nil] The nationality name, or nil if not available
+    def nationality_name
+      nationality.is_a?(TrustID::KDBCountry) ? nationality.name : nil
+    end
+
+    # Get issuing country name (from KDBCountry object if available)
+    #
+    # @return [String, nil] The issuing country name, or nil if not available
+    def issuing_country_name
+      issuing_country.is_a?(TrustID::KDBCountry) ? issuing_country.name : nil
+    end
+
+    # Get the main face image (ImageType 1)
+    #
+    # @return [Image, nil] The face image if found, nil otherwise
+    def face_image
+      return nil unless images.is_a?(Array)
+
+      images.find { |img| img.image_type == 1 }
+    end
+
+    # Get the MRZ image (ImageType 2)
+    #
+    # @return [Image, nil] The MRZ image if found, nil otherwise
+    def mrz_image
+      return nil unless images.is_a?(Array)
+
+      images.find { |img| img.image_type == 2 }
+    end
+
+    # Get all images of a specific type
+    #
+    # @param image_type [Integer] The image type to filter by
+    # @return [Array<Image>] Array of images of the specified type
+    def images_by_type(image_type)
+      return [] unless images.is_a?(Array)
+
+      images.select { |img| img.image_type == image_type }
+    end
+  end
+end

data/lib/trustid_sdk/models/document_configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TrustID
+  # DocumentConfiguration
+  #
+  # Represents document processing/validation configuration from the TrustID API.
+  #
+  # Fields:
+  #   disable_expired_eu_documents_failure - Boolean: If true, the system generates warnings rather than
+  #   failures for expired EU documents.
+  #     (API key: DisableExpiredEUDocumentsFailure; PascalCase key is converted to snake_case by BaseModel.)
+  #   disable_expired_non_eu_documents_failure - Boolean: If true, the system generates warnings rather than
+  #   failures for expired non-EU documents.
+  #     (API key: DisableExpiredNonEuDocumentsFailure; PascalCase key is converted to snake_case by BaseModel.)
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/DocumentConfiguration.html
+  class DocumentConfiguration < BaseModel
+    attribute :disable_expired_eu_documents_failure, :boolean
+    attribute :disable_expired_non_eu_documents_failure, :boolean
+  end
+end