trustid_sdk 0.2.0

data/lib/trustid_sdk/models/filter_date_option.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TrustID
+  # FilterDateOption
+  #
+  # Enum representing date filter options for queries (TrustID API).
+  #
+  # Enum values:
+  #   NONE   (0) - No date filter.
+  #   BEFORE (1) - Filter for dates before the specified value.
+  #   AFTER  (2) - Filter for dates after the specified value.
+  #   EXACT  (3) - Filter for the exact date.
+  #
+  # Use as: FilterDateOption::BEFORE, etc.
+  #
+  # The model exposes a `name_for` method to resolve the code to a human-readable name.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/FilterDateOption.html
+  class FilterDateOption < BaseModel
+    NONE = 0
+    BEFORE = 1
+    AFTER = 2
+    EXACT = 3
+
+    NAMES = {
+      NONE => 'None',
+      BEFORE => 'Before',
+      AFTER => 'After',
+      EXACT => 'Exact'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/flexible_field_data_type.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module TrustID
+  # FlexibleFieldDataType
+  #
+  # Enum representing the data type for a flexible field (TrustID API).
+  #
+  # Enum values:
+  #   INT      (0) - Integer value.
+  #   STRING   (1) - String value.
+  #   DATETIME (2) - DateTime value.
+  #   DECIMAL  (3) - Decimal value.
+  #   ENUM     (4) - Enum value.
+  #
+  # Use as: FlexibleFieldDataType::STRING, etc.
+  #
+  # The model exposes a `name_for` method to resolve the code to a human-readable name.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/FlexibleFieldDataType.html
+  class FlexibleFieldDataType < BaseModel
+    INT = 0
+    STRING = 1
+    DATETIME = 2
+    DECIMAL = 3
+    ENUM = 4
+
+    NAMES = {
+      INT => 'Int',
+      STRING => 'String',
+      DATETIME => 'DateTime',
+      DECIMAL => 'Decimal',
+      ENUM => 'Enum'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/flexible_field_search_specification.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module TrustID
+  # FlexibleFieldSearchSpecification
+  #
+  # Represents search criteria for flexible fields in container searches.
+  #
+  # Fields:
+  #   flexible_field_id         - String: Identifier for the flexible field to search against (or use
+  #   flexible_field_name).
+  #   flexible_field_name       - String: Internal name for the flexible field (exact match, unless
+  #   flexible_field_id is provided).
+  #   __type                    - String: Type of search criteria (e.g. FlexibleFieldSearchStringValues,
+  #   FlexibleFieldSearchEnumValues, etc).
+  #   string_exact_match_list   - Array<String>: Find containers whose field value exactly matches one of
+  #   these (OR logic).
+  #   string_partial_match_list - Array<String>: Find containers whose field value contains any of these
+  #   substrings (OR logic).
+  #   enum_exact_match_list     - Array<String>: Find containers whose field value exactly matches one of
+  #   these enum values (OR logic).
+  #   int_exact_match_list      - Array<Integer>: Find containers whose field value exactly matches one of
+  #   these integers (OR logic).
+  #   int_range_list            - Array<[Integer, Integer]>: Each tuple defines a range of integers to match
+  #   (inclusive, OR logic).
+  #   decimal_exact_match_list  - Array<Decimal>: Find containers whose field value exactly matches one of
+  #   these decimals (OR logic).
+  #   decimal_range_list        - Array<[Decimal, Decimal]>: Each tuple defines a range of decimals to match
+  #   (inclusive, OR logic).
+  #   date_exact_match_list     - Array<Date/DateTime>: Find containers whose field value exactly matches one
+  #   of these dates (OR logic).
+  #   date_range_list           - Array<[Date/DateTime, Date/DateTime]>: Each tuple defines a range of dates
+  #   to match (inclusive, OR logic).
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/FlexibleFieldSearchSpecification.html
+  class FlexibleFieldSearchSpecification < BaseModel
+    # Define all attributes
+    attribute :flexible_field_id, :string
+    attribute :flexible_field_name, :string
+    attribute :__type, :string
+    attribute :string_exact_match_list, default: []
+    attribute :string_partial_match_list, default: []
+    attribute :enum_exact_match_list, default: []
+    attribute :int_exact_match_list, default: []
+    attribute :int_range_list, default: []
+    attribute :decimal_exact_match_list, default: []
+    attribute :decimal_range_list, default: []
+    attribute :date_exact_match_list, default: []
+    attribute :date_range_list, default: []
+  end
+end

data/lib/trustid_sdk/models/flexible_field_specification_search_operator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TrustID
+  # FlexibleFieldSpecificationSearchOperator
+  #
+  # Enum representing how flexible-field search-specification records are to be combined (TrustID API).
+  #
+  # Enum values:
+  #   OR  - Combine search criteria so that not all criteria must match (logical OR).
+  #   AND - Combine search criteria so that all criteria must match (logical AND).
+  #
+  # Use as: FlexibleFieldSpecificationSearchOperator::OR, etc.
+  #
+  # The model exposes a `name_for` method to resolve the code to a human-readable name.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/FlexibleFieldSpecificationSearchOperator.html
+  class FlexibleFieldSpecificationSearchOperator
+    OR = 'OR'
+    AND = 'AND'
+
+    NAMES = {
+      OR => 'OR',
+      AND => 'AND'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/gender.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Enum values (from TrustID API):
+  # 0 - Male
+  # 1 - Female
+  # 2 - Transgender
+  # 3 - Unspecified
+  # 4 - Unknown
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/Gender.html
+  class Gender
+    MALE        = 0
+    FEMALE      = 1
+    TRANSGENDER = 2
+    UNSPECIFIED = 3
+    UNKNOWN     = 4
+
+    NAMES = {
+      MALE => 'Male',
+      FEMALE => 'Female',
+      TRANSGENDER => 'Transgender',
+      UNSPECIFIED => 'Unspecified',
+      UNKNOWN => 'Unknown'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/guest_link_response.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TrustID
+  class GuestLinkResponse < BaseModel
+    # Represents the response from creating a guest link.
+    #
+    # ## Fields
+    # - `access_denied [Boolean]`: Indicates if access was denied.
+    # - `callback_id [String, nil]`: ID of the callback, if any.
+    # - `locked [Boolean]`: Indicates if the guest link is locked.
+    # - `message [String]`: Message about the operation.
+    # - `mfa_code_required [Boolean]`: Indicates if MFA code is required.
+    # - `new_password_required [Boolean]`: Indicates if a new password is required.
+    # - `session_expired [Boolean]`: Indicates if the session has expired.
+    # - `success [Boolean]`: Indicates if the operation was successful.
+    # - `vpe_unreachable [Boolean]`: Indicates if the VPE service is unreachable.
+    # - `csv_rows_imported_count [Integer]`: Number of CSV rows successfully imported.
+    # - `csv_rows_not_imported_count [Integer]`: Number of CSV rows not imported.
+    # - `error_list [Array]`: List of errors, if any.
+    # - `error_messages [Array]`: List of error messages, if any.
+    # - `container_id [String]`: ID of the container created.
+
+    attribute :access_denied, :boolean
+    attribute :callback_id, :string
+    attribute :locked, :boolean
+    attribute :message, :string
+    attribute :mfa_code_required, :boolean
+    attribute :new_password_required, :boolean
+    attribute :session_expired, :boolean
+    attribute :success, :boolean
+    attribute :vpe_unreachable, :boolean
+    attribute :csv_rows_imported_count, :integer
+    attribute :csv_rows_not_imported_count, :integer
+    attribute :error_list, array: true
+    attribute :error_messages, array: true
+    attribute :container_id, :string
+  end
+end

data/lib/trustid_sdk/models/image.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+require_relative 'image_type'
+
+module TrustID
+  class Image < BaseModel
+    # Represents meta data for a document image in TrustID Cloud.
+    #
+    # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/Image.html
+    #
+    # @!attribute [rw] id
+    #   @return [String] The unique identifier of this image record.
+    # @!attribute [rw] document_id
+    #   @return [String] The unique identifier of the document this image belongs to.
+    # @!attribute [rw] container_id
+    #   @return [String] The unique identifier of the container this image belongs to.
+    # @!attribute [rw] image_source_id
+    #   @return [String, nil] If this is a cropped image, the unique identifier of the original image record
+    #   this cropped image is based on.
+    # @!attribute [rw] image_type
+    #   @return [Integer] The type of image (see ImageType enum).
+    # @!attribute [rw] crop_area
+    #   @return [Hash, nil] The crop region in image space (pixels) after rotation, if applicable.
+    # @!attribute [rw] rotation
+    #   @return [Integer, nil] The rotation in degrees (only 90-degree intervals supported), if applicable.
+    # @!attribute [rw] filename
+    #   @return [String, nil] The original name of the uploaded file, if available.
+    # @!attribute [rw] file_type
+    #   @return [Integer] The type of file.
+    # @!attribute [rw] created_at
+    #   @return [String, nil] The timestamp when this image record was created.
+    # @!attribute [rw] current_height
+    #   @return [Integer] The current height of the image in pixels.
+    # @!attribute [rw] current_width
+    #   @return [Integer] The current width of the image in pixels.
+    # @!attribute [rw] current_size
+    #   @return [Integer] The current size of the image in bytes.
+    # @!attribute [rw] original_height
+    #   @return [Integer] The original height of the image in pixels.
+    # @!attribute [rw] original_width
+    #   @return [Integer] The original width of the image in pixels.
+    # @!attribute [rw] original_size
+    #   @return [Integer] The original size of the image in bytes.
+    # @!attribute [rw] time_taken_to_process
+    #   @return [Integer] The time taken to process the image in milliseconds.
+    # @!attribute [rw] time_taken_to_upload
+    #   @return [Integer] The time taken to upload the image in milliseconds.
+    # @!attribute [rw] data
+    #   @return [String, nil] The binary data of the image.
+    # @!attribute [rw] format
+    #   @return [String, nil] The format of the image (e.g., 'jpg', 'png').
+    attribute :id, :string
+    attribute :document_id, :string
+    attribute :container_id, :string
+    attribute :image_source_id, :string
+    attribute :image_type, :integer
+    attribute :crop_area
+    attribute :rotation, :integer
+    attribute :filename, :string
+    attribute :file_type, :integer
+    attribute :created_at, :string
+    attribute :current_height, :integer
+    attribute :current_width, :integer
+    attribute :current_size, :integer
+    attribute :original_height, :integer
+    attribute :original_width, :integer
+    attribute :original_size, :integer
+    attribute :time_taken_to_process, :integer
+    attribute :time_taken_to_upload, :integer
+    attribute :data, :string
+    attribute :format, :string
+
+    # Helper to get image type name
+    #
+    # @return [String, nil] The image type name, or nil if not found
+    def image_type_name
+      ImageType.name_for(image_type)
+    end
+
+    # Initializes an Image object from binary data.
+    #
+    # @param binary_data [String] The binary data of the image.
+    # @return [TrustID::Image] The initialized Image object with inferred format.
+    def self.from_binary(binary_data)
+      format = infer_format(binary_data)
+      new(data: binary_data, format: format)
+    end
+
+    # Infers the format of the image from binary data.
+    #
+    # @param binary_data [String] The binary data of the image.
+    # @return [String, nil] The inferred format of the image (e.g., 'jpg', 'png').
+    def self.infer_format(binary_data)
+      image = MiniMagick::Image.read(binary_data)
+      image.type.downcase
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/trustid_sdk/models/image_orientation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TrustID
+  class ImageOrientation < BaseModel
+    # Represents the orientation of the image as detected by TrustID Cloud.
+    #
+    # This model provides constants representing possible orientations of an image
+    # and a utility method to retrieve the symbolic name for a given orientation value.
+    #
+    # ## Enum Values
+    # - `UNKNOWN_ROTATION (-1)`: The rotation is unknown or not detected.
+    # - `NO_ROTATION (0)`: The document is in the correct orientation.
+    # - `CLOCKWISE (1)`: Rotated clockwise by 90 degrees.
+    # - `COUNTERCLOCKWISE (2)`: Rotated counter-clockwise by 90 degrees.
+    # - `UPSIDEDOWN (3)`: Upside down (180 degrees).
+    #
+    # ## Usage Notes
+    # Use the `name_for` method to retrieve the symbolic name for a given orientation value.
+    #
+    # ## References
+    # [TrustID API Documentation - ImageOrientation](https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ImageOrientation.html)
+    #
+    # Enum values:
+    #   UNKNOWN_ROTATION (-1): The rotation is unknown or not detected.
+    #   NO_ROTATION (0): The document is in the correct orientation.
+    #   CLOCKWISE (1): Rotated clockwise by 90 degrees.
+    #   COUNTERCLOCKWISE (2): Rotated counter-clockwise by 90 degrees.
+    #   UPSIDEDOWN (3): Upside down (180 degrees).
+    #
+    UNKNOWN_ROTATION = -1
+    NO_ROTATION = 0
+    CLOCKWISE = 1
+    COUNTERCLOCKWISE = 2
+    UPSIDEDOWN = 3
+
+    # Mapping of enum values to their symbolic names
+    NAMES = {
+      UNKNOWN_ROTATION => 'UnknownRotation',
+      NO_ROTATION => 'NoRotation',
+      CLOCKWISE => 'Clockwise',
+      COUNTERCLOCKWISE => 'Counterclockwise',
+      UPSIDEDOWN => 'Upsidedown'
+    }.freeze
+
+    # Returns the symbolic name for a given value
+    # @param value [Integer] the orientation value
+    # @return [String, nil] the symbolic name or nil if not found
+    def self.name_for(value)
+      NAMES[value]
+    end
+  end
+end

data/lib/trustid_sdk/models/image_type.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module TrustID
+  class ImageType < BaseModel
+    # Represents the type of a document image as defined by TrustID Cloud.
+    #
+    # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ImageType.html
+    #
+    # Enum values:
+    #   FACE (1): Image of the face of the document holder.
+    #   DOCUMENT (2): Image of the entire document under white light.
+    #   INFRARED (3): Image of the entire document under infrared light.
+    #   ULTRAVIOLET (4): Image of the entire document under ultraviolet light.
+    #   RFID (5): Image of the face of the document holder as stored on the RFID chip.
+    #   BARCODE (6): Image of the barcode area on the document.
+    #   MRZ (7): Image of the machine-readable zone (MRZ) or code line under ultraviolet light.
+    #   FINGERPRINT (8): Image of the fingerprint(s) as stored on the RFID chip.
+    #   DETECTED_FACE (9): Detected image of the face of the document holder.
+    #   OCR (21): Image version prepared for OCR.
+    #   DOCUMENT_BACK (52): Image of the entire document (backside, Non-MRZ) under white light.
+    #   INFRARED_BACK (53): Image of the entire document (backside, Non-MRZ) under infrared light.
+    #   ULTRAVIOLET_BACK (54): Image of the entire document (backside, Non-MRZ) under ultraviolet light.
+    #   ORIGINAL_DOCUMENT (60): The original full document image as obtained or uploaded.
+    #   ORIGINAL_DOCUMENT_BACK (62): The original full rear document image as obtained or uploaded.
+    #   DOCUMENT_SIDE3 (72): Image of the entire document (side 3) under white light.
+    #   INFRARED_SIDE3 (73): Image of the entire document (side 3) under infrared light.
+    #   ULTRAVIOLET_SIDE3 (74): Image of the entire document (side 3) under ultraviolet light.
+    #   DOCUMENT_SIDE4 (82): Image of the entire document (side 4) under white light.
+    #   INFRARED_SIDE4 (83): Image of the entire document (side 4) under infrared light.
+    #   ULTRAVIOLET_SIDE4 (84): Image of the entire document (side 4) under ultraviolet light.
+    #   UNKNOWN (999): The image type is unknown or undefined.
+    #
+    FACE = 1
+    DOCUMENT = 2
+    INFRARED = 3
+    ULTRAVIOLET = 4
+    RFID = 5
+    BARCODE = 6
+    MRZ = 7
+    FINGERPRINT = 8
+    DETECTED_FACE = 9
+    OCR = 21
+    DOCUMENT_BACK = 52
+    INFRARED_BACK = 53
+    ULTRAVIOLET_BACK = 54
+    ORIGINAL_DOCUMENT = 60
+    ORIGINAL_DOCUMENT_BACK = 62
+    DOCUMENT_SIDE3 = 72
+    INFRARED_SIDE3 = 73
+    ULTRAVIOLET_SIDE3 = 74
+    DOCUMENT_SIDE4 = 82
+    INFRARED_SIDE4 = 83
+    ULTRAVIOLET_SIDE4 = 84
+    UNKNOWN = 999
+
+    # Mapping of enum values to their symbolic names
+    NAMES = {
+      FACE => 'Face',
+      DOCUMENT => 'Document',
+      INFRARED => 'Infrared',
+      ULTRAVIOLET => 'Ultraviolet',
+      RFID => 'RFID',
+      BARCODE => 'Barcode',
+      MRZ => 'MRZ',
+      FINGERPRINT => 'Fingerprint',
+      DETECTED_FACE => 'DetectedFace',
+      OCR => 'OCR',
+      DOCUMENT_BACK => 'DocumentBack',
+      INFRARED_BACK => 'InfraredBack',
+      ULTRAVIOLET_BACK => 'UltravioletBack',
+      ORIGINAL_DOCUMENT => 'OriginalDocument',
+      ORIGINAL_DOCUMENT_BACK => 'OriginalDocumentBack',
+      DOCUMENT_SIDE3 => 'DocumentSide3',
+      INFRARED_SIDE3 => 'InfraredSide3',
+      ULTRAVIOLET_SIDE3 => 'UltravioletSide3',
+      DOCUMENT_SIDE4 => 'DocumentSide4',
+      INFRARED_SIDE4 => 'InfraredSide4',
+      ULTRAVIOLET_SIDE4 => 'UltravioletSide4',
+      UNKNOWN => 'Unknown'
+    }.freeze
+
+    # Returns the symbolic name for a given value
+    # @param value [Integer] the image type value
+    # @return [String, nil] the symbolic name or nil if not found
+    def self.name_for(value)
+      NAMES[value]
+    end
+  end
+end

data/lib/trustid_sdk/models/kdb_country.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TrustID
+  class KDBCountry < BaseModel
+    # Represents an issuing country or nationality of the issuing country.
+    #
+    # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/KDBCountry.html
+    #
+    # @!attribute [rw] name
+    #   @return [String] Full name of the country.
+    # @!attribute [rw] nationality
+    #   @return [String] The term for referencing the nationality of the country.
+    # @!attribute [rw] alias1
+    #   @return [String, nil] Common alias name (1).
+    # @!attribute [rw] alias2
+    #   @return [String, nil] Common alias name (2).
+    # @!attribute [rw] alias3
+    #   @return [String, nil] Common alias name (3).
+    # @!attribute [rw] mrz
+    #   @return [String, nil] Encoding format of the country/nationality in the MRZ.
+    # @!attribute [rw] alt_mrz
+    #   @return [String, nil] Alternative encoding format in the MRZ.
+    # @!attribute [rw] uk
+    #   @return [Boolean, nil] True if the country is a member of the United Kingdom.
+    # @!attribute [rw] eu
+    #   @return [Boolean, nil] True if the country is a member state of the European Union.
+    attribute :name, :string
+    attribute :nationality, :string
+    attribute :alias1, :string
+    attribute :alias2, :string
+    attribute :alias3, :string
+    attribute :mrz, :string
+    attribute :alt_mrz, :string
+    attribute :uk, :boolean
+    attribute :eu, :boolean
+  end
+end

data/lib/trustid_sdk/models/kdb_document_number.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Represents the type of document number as defined by TrustID Cloud.
+  #
+  # Enum values (from TrustID API):
+  #   0 - PassportNumber: The primary document number for passports.
+  #   1 - VisaNumber: The primary document number for VISA documents.
+  #   2 - IdentityCardNumber: The primary document number for national id cards.
+  #   3 - DrivingLicenseNumber: The primary document number for driving licences.
+  #   4 - Default: The primary document number is simply stored as primary document number and is not
+  #   available depending on the type of document.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/KDBDocumentNumber.html
+  class KDBDocumentNumber
+    PASSPORT_NUMBER = 0
+    VISA_NUMBER = 1
+    IDENTITY_CARD_NUMBER = 2
+    DRIVING_LICENSE_NUMBER = 3
+    DEFAULT = 4
+
+    NAMES = {
+      PASSPORT_NUMBER => 'PassportNumber',
+      VISA_NUMBER => 'VisaNumber',
+      IDENTITY_CARD_NUMBER => 'IdentityCardNumber',
+      DRIVING_LICENSE_NUMBER => 'DrivingLicenseNumber',
+      DEFAULT => 'Default'
+    }.freeze
+
+    # Returns the symbolic name for a given value
+    # @param value [Integer] the document number type value
+    # @return [String, nil] the symbolic name or nil if not found
+    def self.name_for(value)
+      NAMES[value]
+    end
+  end
+end

data/lib/trustid_sdk/models/kdb_document_sub_type.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TrustID
+  class KDBDocumentSubType < BaseModel
+    # Represents a document sub-type, for example Resident Permit (Visa).
+    #
+    # Fields as per TrustID API documentation:
+    #   id [String]: The unique identifier of this document sub-type.
+    #   name [String]: The name of this document sub-type.
+    #   mrz [String, nil]: The encoding of this document sub-type within the machine-readable zone.
+    #   document_type [String, nil]: The corresponding document type of this document sub-type.
+    #   rewrite_document_type [String, nil]: The document type that should be used for this document sub-type
+    #   (for normalisation/correction).
+    #   rewrite_document_number [Integer, nil]: The type of document number to use for this sub-type (see
+    #   KDBDocumentNumber).
+    attribute :id, :string
+    attribute :name, :string
+    attribute :mrz, :string
+    attribute :document_type, :string
+    attribute :rewrite_document_type, :string
+    attribute :rewrite_document_number, :integer
+
+    # Optionally, you may want to add initialization and type validation logic here if needed.
+    # def initialize(attributes = {})
+    #   ...
+    # end
+  end
+end

data/lib/trustid_sdk/models/kdb_feature_type.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Represents the type of document feature as defined by TrustID Cloud.
+  #
+  # Enum values (from TrustID API):
+  #   0 - FULL_DOCUMENT_COMPARISON: Comparing the entire document with a sample image.
+  #   1 - HOLOGRAM: Comparing a hologram feature with a sample and instructions how to correctly check holograms.
+  #   2 - PRIMARY_FACE: The primary facial image of the document holder.
+  #   3 - PRIMARY_FACE_AND_COLOUR_VS_IR: Comparing the primary facial image under visual light vs infrared.
+  #   4 - SECONDARY_FACE: Secondary facial image of the document holder.
+  #   5 - SCANNED_VS_STOCK: Compare scanned document against a similar sample document.
+  #   6 - COLOUR_VS_IR: Compare the document under visual light against the same document under infrared.
+  #   7 - OCR: The region on the document that is captured through optical character recognition (OCR).
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/KDBFeatureType.html
+  class KDBFeatureType
+    FULL_DOCUMENT_COMPARISON = 0
+    HOLOGRAM = 1
+    PRIMARY_FACE = 2
+    PRIMARY_FACE_AND_COLOUR_VS_IR = 3
+    SECONDARY_FACE = 4
+    SCANNED_VS_STOCK = 5
+    COLOUR_VS_IR = 6
+    OCR = 7
+
+    NAMES = {
+      FULL_DOCUMENT_COMPARISON => 'FullDocumentComparison',
+      HOLOGRAM => 'Hologram',
+      PRIMARY_FACE => 'PrimaryFace',
+      PRIMARY_FACE_AND_COLOUR_VS_IR => 'PrimaryFaceAndColourVsIR',
+      SECONDARY_FACE => 'SecondaryFace',
+      SCANNED_VS_STOCK => 'ScannedVsStock',
+      COLOUR_VS_IR => 'ColourVsIR',
+      OCR => 'OCR'
+    }.freeze
+
+    # Returns the symbolic name for a given value
+    # @param value [Integer] the feature type value
+    # @return [String, nil] the symbolic name or nil if not found
+    def self.name_for(value)
+      NAMES[value]
+    end
+  end
+end

data/lib/trustid_sdk/models/liveness_result_type.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Represents the result of a liveness test as detected by TrustID Cloud.
+  #
+  # This model provides constants representing possible outcomes of a liveness test
+  # and a utility method to retrieve the symbolic name for a given result code.
+  #
+  # ## Enum Values
+  # - `NOT_LIVE (0)`: The liveness test has not been performed.
+  # - `LIVE (1)`: The liveness test was successful.
+  # - `ERROR (2)`: The liveness test failed.
+  # - `POOR_IMAGE_QUALITY (3)`: The image quality is too poor to perform the test.
+  # - `FACE_TOO_CLOSE (4)`: The face is too close to the camera.
+  # - `FACE_NOT_FOUND (5)`: No face was detected in the image.
+  # - `FACE_TOO_SMALL (6)`: The face is too small to perform the test.
+  # - `FACE_ANGLE_TOO_LARGE (7)`: The face angle is too large for a valid test.
+  # - `FAILED_TO_READ_IMAGE (8)`: The image could not be read.
+  # - `UNKNOWN (9)`: The result is unknown or not recognized.
+  #
+  # ## Usage Notes
+  # Use the `name_for` method to retrieve the symbolic name for a given result code.
+  #
+  # ## References
+  # [TrustID API Documentation - LivenessResultType](https://developer.trustid.co.uk/documentation/ref/raw_ref/model/LivenessResultType.html)
+  class LivenessResultType
+    NOT_LIVE           = 0
+    LIVE               = 1
+    ERROR              = 2
+    POOR_IMAGE_QUALITY = 3
+    FACE_TOO_CLOSE     = 4
+    FACE_NOT_FOUND     = 5
+    FACE_TOO_SMALL     = 6
+    FACE_ANGLE_TOO_LARGE = 7
+    FAILED_TO_READ_IMAGE = 8
+    UNKNOWN = 9
+
+    NAMES = {
+      NOT_LIVE => 'NotLive',
+      LIVE => 'Live',
+      ERROR => 'Error',
+      POOR_IMAGE_QUALITY => 'PoorImageQuality',
+      FACE_TOO_CLOSE => 'FaceTooClose',
+      FACE_NOT_FOUND => 'FaceNotFound',
+      FACE_TOO_SMALL => 'FaceTooSmall',
+      FACE_ANGLE_TOO_LARGE => 'FaceAngleTooLarge',
+      FAILED_TO_READ_IMAGE => 'FailedToReadImage',
+      UNKNOWN => 'Unknown'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end