trustid_sdk 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 301c57a0d10d984e3596a83163bac369d92daee4cc785a90553c0f6d958f3be7
+  data.tar.gz: 87e4f7fa237313d37ecc7b640239bebfe9353355e4e3f7e5cd338364637baf07
+SHA512:
+  metadata.gz: '09df2387ca97b8753e74c36fe72fddd3cb929bd1e02114e89151cb278e68471157e03d506d72c7ec4b23329c9446f2045f84117067ee5c7f81f6c6de7b22de4b'
+  data.tar.gz: c493a5aea56b14f9d85dfd30b6f11e8026bc82f976e524824977263e42da19fc738e224fb1dd92ee352b9ba825f95a7fa9e2245ded1e003041a2895c2982285e

data/README.md

@@ -0,0 +1,80 @@
+# TrustID SDK
+
+A modular Ruby SDK for interacting with the TrustID API.
+
+## Installation
+
+```bash
+gem install trustid_sdk
+```
+
+## Configuration
+
+### Production Mode
+```ruby
+TrustID.configure do |config|
+  config.username = ENV["TRUSTID_USERNAME"]
+  config.password = ENV["TRUSTID_PASSWORD"]
+  config.api_key = ENV["TRUSTID_API_KEY"]
+  # Optional: Override default production URL
+  # config.server_url = "https://custom-production-url.com"
+end
+```
+
+### Sandbox Mode
+```ruby
+TrustID.configure do |config|
+  config.username = ENV["TRUSTID_USERNAME"]
+  config.password = ENV["TRUSTID_PASSWORD"]
+  config.api_key = ENV["TRUSTID_API_KEY"]
+  config.sandbox_mode = true
+  # Optional: Override default sandbox URL
+  # config.server_url = "https://custom-sandbox-url.com"
+end
+```
+
+### Device ID
+
+`device_id` can be a string or a proc (or any object that responds to `call`). When it is a proc, it is invoked each time the SDK needs the device ID (e.g. for requests and reports), and the returned value is used.
+
+This is particularly useful for **parallel usage**: if you run multiple clients or workers, each needs a distinct device ID and session. If you reuse the same device ID, the next login for that device invalidates the previous session. Setting `device_id` to a proc that returns a new value per client (e.g. `-> { "prefix-#{SecureRandom.uuid}" }`) ensures each logical “device” gets a unique ID and its own session.
+
+```ruby
+require 'securerandom'
+
+TrustID.configure do |config|
+  config.username = ENV["TRUSTID_USERNAME"]
+  config.password = ENV["TRUSTID_PASSWORD"]
+  config.api_key = ENV["TRUSTID_API_KEY"]
+  # Unique device ID per client/worker so each has its own session
+  config.device_id = -> { "worker-#{SecureRandom.uuid}" }
+end
+```
+
+## Usage
+
+```ruby
+client = TrustID::Client.new
+
+TrustID::Services::GuestLinks.create(email: "jane@example.com", name: "Jane Example")
+TrustID::Services::Containers.retrieve(container_id: "abc123")
+TrustID::Services::Documents.retrieve(container_id: "abc123", document_id: "doc456")
+image_data = TrustID::Services::Images.retrieve(image_id: "img789")
+
+# Export PDF report (recommended - uses POST with JSON, more secure)
+pdf = TrustID::Services::Reports.find_report(container_id: "abc123")
+
+# Download PDF using GET request
+pdf = TrustID::Services::Reports.find_pdf(container_id: "abc123")
+
+# Generate a download link URL for embedding in HTML
+download_url = TrustID::Services::Reports.download_link(container_id: "abc123")
+# Use in HTML: <a href="#{download_url}" download>Download PDF</a>
+```
+
+## Development
+
+```bash
+bundle install
+rspec
+```

data/lib/trustid_sdk/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TrustID
+  class Client
+    attr_reader :server_url
+    attr_accessor :session_id
+
+    def initialize
+      config = TrustID.config
+      @device_id = config.device_id
+      @server_url = config.server_url
+      TrustID.client = self
+      Services::Authentication.new(config.username, config.password).login
+    end
+
+    def device_id
+      value = @device_id
+      value.respond_to?(:call) ? value.call : value
+    end
+  end
+end

data/lib/trustid_sdk/concerns/attribute_resolution.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TrustID
+  module AttributeResolution
+    private
+
+    def resolve_enum(value, enum_module)
+      return nil if value.nil?
+
+      enum_module.respond_to?(:name_for) ? enum_module.name_for(value) : value
+    end
+
+    def resolve_model(value, klass)
+      return klass.new({}) if value.nil?
+
+      value.is_a?(klass) ? value : klass.new(value)
+    end
+  end
+end

data/lib/trustid_sdk/concerns/has_nested_models.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module TrustID
+  # HasNestedModels is a concern that allows models to define nested models
+  # with support for single objects or arrays. It provides methods to define
+  # nested models, handle attribute extraction, and create instances from hashes.
+  module HasNestedModels
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(ActiveModel::Model) unless base.include?(ActiveModel::Model)
+      base.include(ActiveModel::Attributes) unless base.include?(ActiveModel::Attributes)
+    end
+
+    # ClassMethods module to define nested models
+    module ClassMethods
+      # Register a nested model (single object or array)
+      def nested_model(attr, klass, array: false, keys: nil)
+        keys ||= infer_keys(attr, klass)
+        nested_model_definitions[attr.to_s] = {
+          klass: klass,
+          array: array,
+          keys: keys
+        }
+        define_nested_model_accessors(attr)
+      end
+
+      def nested_model_definitions
+        @nested_model_definitions ||= {}
+      end
+
+      # Helper method to extract attributes with multiple potential keys
+      def extract_attribute(attrs, *keys)
+        keys.each do |key|
+          if attrs.key?(key)
+            value = attrs.delete(key)
+            return value unless value.nil?
+          end
+        end
+        nil
+      end
+
+      # Helper to create model instance from hash
+      def create_nested_instance(klass, data)
+        return nil if data.nil?
+        return data if data.is_a?(klass)
+
+        klass.respond_to?(:from_hash) ? klass.from_hash(data) : klass.new(data)
+      end
+
+      private
+
+      def define_nested_model_accessors(attr)
+        define_method(attr) { instance_variable_get("@#{attr}") }
+        define_method("#{attr}=") do |value|
+          config = self.class.nested_model_definitions[attr.to_s]
+          processed = self.class.process_nested_value(config, value)
+          instance_variable_set("@#{attr}", processed)
+        end
+      end
+
+      def process_nested_value(config, value)
+        if config[:array]
+          Array(value).map { |item| create_nested_instance(config[:klass], item) }.compact
+        else
+          create_nested_instance(config[:klass], value)
+        end
+      end
+      public :process_nested_value
+
+      def infer_keys(attr, klass)
+        attr_str = attr.to_s
+        attr_sym = attr.to_sym
+        camel = attr_str.camelize
+        camel_sym = camel.to_sym
+        klass_str = klass.name.split('::').last
+        [
+          attr_str, camel, attr_sym, camel_sym,
+          klass_str, klass_str.underscore, klass_str.to_sym, klass_str.underscore.to_sym
+        ].uniq
+      end
+    end
+
+    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)
+
+      # Extract nested model data and assign to normalized keys
+      nested_values = {}
+      self.class.nested_model_definitions.each do |attr, config|
+        value = nil
+        config[:keys].each do |key|
+          key_str = key.to_s
+          if attrs.key?(key_str)
+            value = attrs.delete(key_str)
+            break if value
+          end
+        end
+        attrs[attr.to_s] = value if value
+        nested_values[attr] = value if value
+      end
+
+      # Initialize with normalized attributes
+      super
+
+      # Always call the setter for each nested attribute to ensure type conversion
+      nested_values.each do |attr, value|
+        next if value.nil?
+
+        send("#{attr}=", value)
+      end
+    end
+
+    def assign_attributes(new_attributes)
+      return unless new_attributes
+
+      # Handle nested attributes first
+      nested_attrs = {}
+      self.class.nested_model_definitions.each do |attr, config|
+        config[:keys].each do |key|
+          next unless new_attributes.key?(key.to_s) || new_attributes.key?(key.to_sym)
+
+          value = new_attributes.delete(key.to_s) || new_attributes.delete(key.to_sym)
+          nested_attrs[attr] = value unless value.nil?
+          break
+        end
+      end
+
+      # Update nested models
+      nested_attrs.each do |attr, value|
+        send("#{attr}=", value)
+      end
+
+      # Handle remaining attributes
+      super
+    end
+
+    def process_nested_models
+      return unless defined?(@nested_data) && @nested_data.is_a?(Hash)
+
+      self.class.nested_model_definitions.each do |attr, config|
+        next unless @nested_data[attr]
+
+        value = @nested_data[attr]
+        processed_value = if config[:array]
+                            value.map { |item| self.class.create_nested_instance(config[:klass], item) }.compact
+                          else
+                            self.class.create_nested_instance(config[:klass], value)
+                          end
+
+        instance_variable_set("@#{attr}", processed_value)
+        define_accessors(attr)
+      end
+    end
+
+    protected
+
+    def define_accessors(attr_name)
+      unless respond_to?(attr_name)
+        define_singleton_method(attr_name) do
+          instance_variable_get("@#{attr_name}")
+        end
+      end
+
+      return if respond_to?("#{attr_name}=")
+
+      define_singleton_method("#{attr_name}=") do |value|
+        config = self.class.nested_model_definitions[attr_name]
+
+        processed = if config[:array]
+                      Array(value).map { |item| self.class.create_nested_instance(config[:klass], item) }.compact
+                    else
+                      self.class.create_nested_instance(config[:klass], value)
+                    end
+
+        instance_variable_set("@#{attr_name}", processed)
+      end
+    end
+  end
+end

data/lib/trustid_sdk/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Main module for TrustID SDK functionality
+module TrustID
+  # Configuration class for TrustID SDK settings
+  class Config
+    attr_accessor :username, :password, :device_id, :api_key
+
+    def initialize
+      @sandbox_mode = false
+      @api_header_key = 'Tid-Api-Key'
+    end
+
+    def sandbox_mode=(mode)
+      @sandbox_mode = mode
+      # Set default server URL based on mode if not explicitly set
+      @server_url = default_server_url if @server_url.nil?
+    end
+
+    attr_reader :api_header_key, :sandbox_mode
+    attr_writer :server_url
+
+    def server_url
+      @server_url ||= default_server_url
+    end
+
+    def debug_mode=(debug_mode = false)
+      TrustID.debug_mode = debug_mode
+    end
+
+    private
+
+    def default_server_url
+      @sandbox_mode ? 'https://sandbox.trustid.co.uk' : 'https://cloud.trustid.co.uk'
+    end
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+end

data/lib/trustid_sdk/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TrustID
+  module Errors
+    class ClientError < StandardError; end
+
+    class APIError < StandardError
+      attr_reader :response
+
+      def initialize(response)
+        @message = response['Message']
+        @response = response
+        super(@message)
+      end
+    end
+
+    class AuthenticationError < APIError; end
+    class BadRequestError < APIError; end
+    class UnauthorizedError < APIError; end
+    class ForbiddenError < APIError; end
+    class NotFoundError < APIError; end
+  end
+end

data/lib/trustid_sdk/models/access_lock.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Represents locking information for shared resources on TrustID Cloud.
+  #
+  # Fields as per TrustID API documentation:
+  #   anonymous_session_id [String]: SHA256 hash of session id.
+  #   locked [Boolean]: Whether the resource is locked.
+  #   timestamp [DateTime]: ISO8601 datetime of the lock.
+  #   user_display [String]: Display name of the user holding the lock.
+  #   user_id [String]: ID of the user holding the lock.
+  #   user [User, nil]: User model (resolved if present).
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/AccessLock.html
+  class AccessLock < BaseModel
+    attribute :anonymous_session_id, :string
+    attribute :locked, :boolean
+    attribute :timestamp, :datetime
+    attribute :user_display, :string
+    attribute :user_id, :string
+    attr_reader :user
+
+    def initialize(attributes = {})
+      super
+      @user = resolve_model(attributes[:user], TrustID::User)
+    end
+  end
+end

data/lib/trustid_sdk/models/advanced_query_arguments.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require_relative '../concerns/attribute_resolution'
+
+module TrustID
+  # Represents advanced query arguments for searching documents and applications in the TrustID API.
+  #
+  # Fields as per TrustID API documentation:
+  #   status [Integer]: Status code to filter by.
+  #   audited [Boolean]: Whether the record is audited.
+  #   mrz_corrected [Boolean]: Whether the MRZ was corrected.
+  #   min_age_failed [Integer]: Minimum age failure filter.
+  #   max_age_failed [Integer]: Maximum age failure filter.
+  #   quick_query [String]: Quick search string.
+  #   firstname [String]: First name filter.
+  #   lastname [String]: Last name filter.
+  #   nationality_code [String]: Nationality code filter.
+  #   issuing_country_code [String]: Issuing country code filter.
+  #   document_number [String]: Document number filter.
+  #   passport_number [String]: Passport number filter.
+  #   visa_number [String]: Visa number filter.
+  #   identity_card_number [String]: Identity card number filter.
+  #   driving_license_number [String]: Driving license number filter.
+  #   document_type [Integer]: Document type filter.
+  #   personal_number [String]: Personal number filter.
+  #   expiry_date [Date]: Expiry date filter.
+  #   date_of_birth [Date]: Date of birth filter.
+  #   scanned_by [String]: Scanned by user filter.
+  #   audited_by [String]: Audited by user filter.
+  #   branch_name [String]: Branch name filter.
+  #   gender [Gender, nil]: Gender filter (enum).
+  #   mrz_query_option [MrzQueryOption, nil]: MRZ query option (enum).
+  #   filter_expiry_date_option [FilterDateOption, nil]: Expiry date filter option (enum).
+  #   filter_date_of_birth_date_option [FilterDateOption, nil]: Date of birth filter option (enum).
+  #   custom_fields [Array<CustomField>]: Custom field filters.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/AdvancedQueryArguments.html
+  class AdvancedQueryArguments < BaseModel
+    # Simple attributes
+    attribute :status, :integer
+    attribute :audited, :boolean
+    attribute :mrz_corrected, :boolean
+    attribute :min_age_failed, :integer
+    attribute :max_age_failed, :integer
+    attribute :quick_query, :string
+    attribute :firstname, :string
+    attribute :lastname, :string
+    attribute :nationality_code, :string
+    attribute :issuing_country_code, :string
+    attribute :document_number, :string
+    attribute :passport_number, :string
+    attribute :visa_number, :string
+    attribute :identity_card_number, :string
+    attribute :driving_license_number, :string
+    attribute :document_type, :integer
+    attribute :personal_number, :string
+    attribute :expiry_date, :date
+    attribute :date_of_birth, :date
+    attribute :scanned_by, :string
+    attribute :audited_by, :string
+    attribute :branch_name, :string
+
+    # Expose nested/enum attributes as readers
+    attr_reader :gender, :mrz_query_option, :filter_expiry_date_option, :filter_date_of_birth_date_option,
+                :custom_fields
+
+    def initialize(attributes = {})
+      super
+      @gender = resolve_enum(attributes[:gender], TrustID::Gender)
+      @mrz_query_option = resolve_enum(attributes[:mrz_query_option], TrustID::MrzQueryOption)
+      @filter_expiry_date_option = resolve_enum(attributes[:filter_expiry_date_option], TrustID::FilterDateOption)
+      @filter_date_of_birth_date_option = resolve_enum(attributes[:filter_date_of_birth_date_option],
+                                                       TrustID::FilterDateOption)
+      @custom_fields = Array(attributes[:custom_fields]).map { |cf| resolve_model(cf, TrustID::CustomField) }
+    end
+  end
+end

data/lib/trustid_sdk/models/application_flexible_field.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TrustID
+  # ApplicationFlexibleField
+  #
+  # Enum representing the types of flexible fields that can be associated with an application.
+  #
+  # Enum values:
+  #   NEW_APPLICATION_FIELD             (1)   - New application field.
+  #   NEW_QUEUED_APPLICATION_FIELD      (2)   - New queued application field.
+  #   POPULATE_QUEUED_APPLICATION_FIELD (4)   - Populate queued application field.
+  #   NEW_GUEST_LINK_FIELD              (256) - New guest link field.
+  #
+  # Use as: ApplicationFlexibleField::NEW_APPLICATION_FIELD, etc.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ApplicationFlexibleField.html
+  class ApplicationFlexibleField
+    NEW_APPLICATION_FIELD             = 1
+    NEW_QUEUED_APPLICATION_FIELD      = 2
+    POPULATE_QUEUED_APPLICATION_FIELD = 4
+    NEW_GUEST_LINK_FIELD              = 256
+
+    NAMES = {
+      NEW_APPLICATION_FIELD => 'NewApplicationField',
+      NEW_QUEUED_APPLICATION_FIELD => 'NewQueuedApplicationField',
+      POPULATE_QUEUED_APPLICATION_FIELD => 'PopulateQueuedApplicationField',
+      NEW_GUEST_LINK_FIELD => 'NewGuestLinkField'
+    }.freeze
+
+    def self.name_for(code)
+      NAMES[code]
+    end
+  end
+end

data/lib/trustid_sdk/models/application_flexible_field_attribute.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Represents a template for an application-level custom field (flexible field attribute).
+  # Application flexible fields are associated with document containers.
+  #
+  # Fields as per TrustID API documentation:
+  #   branch_id [String]: The branch that applies to this field.
+  #   creation_date [DateTime]: When this field was created.
+  #   data_range [String]: Comma-separated list of possible values if enum.
+  #   data_type [Integer]: See FlexibleFieldDataType.
+  #   default_value [String]: The default value for this field.
+  #   display_name [String]: Display name for the field.
+  #   entity_id [String]: The entity ID associated with this field.
+  #   field_order_index [Integer]: Order in which field is presented.
+  #   flags [Integer]: Flags associated with this field.
+  #   flexible_field_id [String]: Unique identifier shared between all versions.
+  #   help_text [String]: Help information for the user.
+  #   id [String]: Unique version identifier.
+  #   is_active [Boolean]: True if this is the active version.
+  #   is_enabled [Boolean]: True if the field is enabled.
+  #   is_global [Boolean]: True if the field is global.
+  #   is_validation_field [Boolean]: True if validated against pass/warn/fail.
+  #   last_modifield [DateTime]: When this field was last modified.
+  #   mandatory [Boolean]: True if this field is mandatory.
+  #   name [String]: Internal name.
+  #   validation_fail_value [String]: Value considered a fail.
+  #   validation_pass_value [String]: Value considered a pass.
+  #   validation_warning_value [String]: Value considered a warning.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ApplicationFlexibleFieldAttribute.html
+  class ApplicationFlexibleFieldAttribute < BaseModel
+    # Explicitly define all attributes found in the API response
+    attribute :branch_id, :string
+    attribute :creation_date, :datetime
+    attribute :data_range, :string
+    attribute :data_type, :integer
+    attribute :default_value, :string
+    attribute :display_name, :string
+    attribute :entity_id, :string
+    attribute :field_order_index, :integer
+    attribute :flags, :integer
+    attribute :flexible_field_id, :string
+    attribute :help_text, :string
+    attribute :id, :string
+    attribute :is_active, :boolean
+    attribute :is_enabled, :boolean
+    attribute :is_global, :boolean
+    attribute :is_validation_field, :boolean
+    attribute :last_modifield, :datetime
+    attribute :mandatory, :boolean
+    attribute :name, :string
+    attribute :validation_fail_value, :string
+    attribute :validation_pass_value, :string
+    attribute :validation_warning_value, :string
+
+    def initialize(attributes = {})
+      # Normalize keys to handle API response format
+      attributes = normalize_keys(attributes)
+      super
+    end
+
+    private
+
+    # Helper method to normalize keys to lowercase 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/application_flexible_field_list.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative 'application_flexible_field_attribute'
+require_relative 'application_flexible_field_value'
+
+module TrustID
+  # ApplicationFlexibleFieldList
+  #
+  # Represents a single pair of (attribute, value) for a custom application field.
+  #
+  # This is a value object that wraps a single pair, not a true list or collection.
+  #
+  # Fields:
+  #   attribute - ApplicationFlexibleFieldAttribute: The type/metadata for the custom field.
+  #   value     - ApplicationFlexibleFieldValue: The value for the custom field.
+  #
+  # When initialized, this model expects a hash with either:
+  #   - keys :m_Item1 and :m_Item2 (as returned by the TrustID API), or
+  #   - keys :attribute and :value (for internal use).
+  #
+  # The model will resolve and wrap the attribute and value using their respective models.
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/ApplicationFlexibleFieldList.html
+  class ApplicationFlexibleFieldList < BaseModel
+    attr_reader :attribute, :value
+
+    attribute :m_item1 # For API compatibility
+    attribute :m_item2 # For API compatibility
+
+    def initialize(attributes = {})
+      # Normalize attribute keys
+      attributes = normalize_keys(attributes)
+
+      # Extract attribute and value data
+      @attribute_data = attributes.delete(:m_item1) || attributes.delete('m_item1') ||
+                        attributes.delete(:attribute) || attributes.delete('attribute')
+      @value_data = attributes.delete(:m_item2) || attributes.delete('m_item2') ||
+                    attributes.delete(:value) || attributes.delete('value')
+
+      # Initialize with remaining attributes
+      super
+
+      # Process nested models
+      process_nested_models
+    end
+
+    def process_nested_models
+      self.attribute = @attribute_data if @attribute_data
+      self.value = @value_data if @value_data
+    end
+
+    def attribute=(data)
+      @attribute = if data.is_a?(TrustID::ApplicationFlexibleFieldAttribute)
+                     data
+                   else
+                     TrustID::ApplicationFlexibleFieldAttribute.from_hash(data)
+                   end
+    end
+
+    def value=(data)
+      @value = if data.is_a?(TrustID::ApplicationFlexibleFieldValue)
+                 data
+               else
+                 TrustID::ApplicationFlexibleFieldValue.from_hash(data)
+               end
+    end
+
+    private
+
+    def normalize_keys(hash)
+      result = {}
+      hash.each do |key, value|
+        normalized_key = key.to_s.downcase.to_sym
+        result[normalized_key] = value
+      end
+      result
+    end
+  end
+end