trustid_sdk 0.2.0

data/lib/trustid_sdk/models/webhook_data.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require_relative 'webhook_response'
+require_relative 'container'
+require_relative 'document'
+
+module TrustID
+  # WebhookData
+  #
+  # Enhanced webhook data object that provides fetch methods for related resources.
+  # This class wraps a WebhookResponse and adds convenience methods for fetching
+  # containers, documents, and other related resources.
+  class WebhookData
+    attr_reader :webhook_response
+
+    def initialize(webhook_response)
+      @webhook_response = webhook_response
+    end
+
+    # Delegate all methods to the underlying webhook_response
+    def method_missing(method_name, *, &)
+      if webhook_response.respond_to?(method_name)
+        webhook_response.send(method_name, *, &)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      webhook_response.respond_to?(method_name, include_private) || super
+    end
+
+    # Fetch the container associated with this webhook
+    #
+    # @return [Container, nil] The container if found, nil otherwise
+    def fetch_container
+      container_id = self.container_id || callback&.container_id
+      return nil unless container_id
+
+      Container.find(container_id)
+    rescue StandardError => e
+      warn "Failed to fetch container #{container_id}: #{e.message}"
+      nil
+    end
+
+    # Get the container associated with this webhook (cached)
+    #
+    # @return [Container, nil] The container if found, nil otherwise
+    def container
+      @container ||= fetch_container
+    end
+
+    # Fetch the document associated with this webhook
+    #
+    # @return [Document, nil] The document if found, nil otherwise
+    def fetch_document
+      document_id = callback&.document_id
+      return nil unless document_id
+
+      Document.find(document_id)
+    rescue StandardError => e
+      warn "Failed to fetch document #{document_id}: #{e.message}"
+      nil
+    end
+
+    # Get the document associated with this webhook (cached)
+    #
+    # @return [Document, nil] The document if found, nil otherwise
+    def document
+      @document ||= fetch_document
+    end
+
+    # Get the container ID from either the response or callback
+    #
+    # @return [String, nil] The container ID
+    def effective_container_id
+      container_id || callback&.container_id
+    end
+
+    # Get the document ID from the callback
+    #
+    # @return [String, nil] The document ID
+    def effective_document_id
+      callback&.document_id
+    end
+
+    # Get the client application reference from the callback
+    #
+    # @return [String, nil] The client application reference
+    def effective_client_application_reference
+      callback&.client_application_reference
+    end
+
+    # Check if this webhook has a container
+    #
+    # @return [Boolean] True if a container ID is present
+    def container?
+      effective_container_id.present?
+    end
+
+    # Check if this webhook has a document
+    #
+    # @return [Boolean] True if a document ID is present
+    def document?
+      effective_document_id.present?
+    end
+
+    # Get a summary of the webhook data
+    #
+    # @return [Hash] Summary information
+    def summary
+      {
+        success: success,
+        operation_successful: operation_successful?,
+        container_id: effective_container_id,
+        document_id: effective_document_id,
+        client_application_reference: effective_client_application_reference,
+        workflow_name: workflow_name,
+        workflow_state: workflow_state,
+        message: message,
+        has_callback: callback?,
+        has_container: container?,
+        has_document: document?
+      }
+    end
+
+    # Build a complete JSON representation of the webhook data including fetched resources
+    #
+    # @param include_resources [Boolean] Whether to include fetched container and document data
+    # @return [Hash] Complete webhook data structure
+    def to_json_data(include_resources: true)
+      data = {
+        webhook_response: webhook_response_to_hash,
+        effective_values: build_effective_values,
+        availability: build_availability,
+        summary: summary
+      }
+
+      data[:fetched_resources] = build_fetched_resources if include_resources
+
+      data
+    end
+
+    # Convert webhook data to JSON string
+    #
+    # @param include_resources [Boolean] Whether to include fetched container and document data
+    # @param pretty [Boolean] Whether to format JSON with indentation
+    # @return [String] JSON string representation
+    def to_json(include_resources: true, pretty: false)
+      require 'json'
+      data = to_json_data(include_resources: include_resources)
+
+      if pretty
+        JSON.pretty_generate(data)
+      else
+        data.to_json
+      end
+    end
+
+    # Save webhook data to a JSON file
+    #
+    # @param file_path [String] Path to save the JSON file
+    # @param include_resources [Boolean] Whether to include fetched container and document data
+    # @param pretty [Boolean] Whether to format JSON with indentation
+    # @return [Boolean] True if file was saved successfully
+    def save_to_file(file_path, include_resources: true, pretty: true)
+      require 'json'
+
+      json_data = to_json(include_resources: include_resources, pretty: pretty)
+      File.write(file_path, json_data)
+      true
+    rescue StandardError => e
+      warn "Failed to save webhook data to #{file_path}: #{e.message}"
+      false
+    end
+
+    private
+
+    def build_effective_values
+      {
+        container_id: effective_container_id,
+        document_id: effective_document_id,
+        client_application_reference: effective_client_application_reference
+      }
+    end
+
+    def build_availability
+      {
+        has_container: container?,
+        has_document: document?,
+        has_callback: callback?
+      }
+    end
+
+    def build_fetched_resources
+      {
+        container: container&.to_hash,
+        document: document&.to_hash
+      }
+    end
+
+    # Convert webhook response to hash representation
+    #
+    # @return [Hash] Webhook response as hash
+    def webhook_response_to_hash
+      {
+        callback: callback_to_hash,
+        response: response_to_hash,
+        success: webhook_response.success,
+        message: webhook_response.message,
+        container_id: webhook_response.container_id,
+        access_denied: webhook_response.access_denied,
+        locked: webhook_response.locked,
+        session_expired: webhook_response.session_expired,
+        vpe_unreachable: webhook_response.vpe_unreachable,
+        auto_referred: webhook_response.auto_referred,
+        document_replaced: webhook_response.document_replaced,
+        merge_containers: webhook_response.merge_containers,
+        merged: webhook_response.merged
+      }
+    end
+
+    # Convert callback to hash representation
+    #
+    # @return [Hash] Callback as hash
+    def callback_to_hash
+      return nil unless webhook_response.callback
+
+      callback = webhook_response.callback
+      {
+        aborted: callback.aborted,
+        callback_at: callback.callback_at&.iso8601,
+        callback_id: callback.callback_id,
+        callback_status_code: callback.callback_status_code,
+        callback_url: callback.callback_url,
+        error_message: callback.error_message,
+        process_name: callback.process_name,
+        retry_counter: callback.retry_counter,
+        scheduled_at: callback.scheduled_at&.iso8601,
+        state: callback.state,
+        updated_at: callback.updated_at&.iso8601,
+        workflow_name: callback.workflow_name,
+        workflow_state: callback.workflow_state,
+        workflow_storage: callback.workflow_storage&.map(&:to_hash),
+        # Helper values
+        container_id: callback.container_id,
+        document_id: callback.document_id,
+        client_application_reference: callback.client_application_reference
+      }
+    end
+
+    # Convert response to hash representation
+    #
+    # @return [Hash] Response as hash
+    def response_to_hash
+      {
+        access_denied: webhook_response.access_denied,
+        callback_id: webhook_response.callback_id,
+        locked: webhook_response.locked,
+        message: webhook_response.message,
+        session_expired: webhook_response.session_expired,
+        success: webhook_response.success,
+        vpe_unreachable: webhook_response.vpe_unreachable,
+        auto_referred: webhook_response.auto_referred,
+        container_id: webhook_response.container_id,
+        document_replaced: webhook_response.document_replaced,
+        merge_containers: webhook_response.merge_containers,
+        merged: webhook_response.merged
+      }
+    end
+  end
+end

data/lib/trustid_sdk/models/webhook_response.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative 'webhook_callback'
+
+module TrustID
+  # Represents a webhook response as per TrustID API.
+  #
+  # This model provides details about the webhook response, including the process name,
+  # retry attempts, workflow details, and the success status of the operation.
+  #
+  # ## Fields
+  # - `callback [WebhookCallback, nil]`: The callback object containing detailed callback information.
+  # - `response [Hash, nil]`: The response object containing operation results.
+  # - `access_denied [Boolean, nil]`: Whether access was denied.
+  # - `callback_id [String, nil]`: ID of the callback, if any.
+  # - `locked [Boolean, nil]`: Whether the resource is locked.
+  # - `message [String, nil]`: Message about the operation (usually 'Operation executed successfully.').
+  # - `session_expired [Boolean, nil]`: Whether the session has expired.
+  # - `success [Boolean, nil]`: Whether the operation was successful.
+  # - `vpe_unreachable [Boolean, nil]`: Whether the VPE is unreachable.
+  # - `auto_referred [Boolean, nil]`: Whether the operation was auto-referred.
+  # - `container_id [String, nil]`: Unique ID of the check in TrustID servers.
+  # - `document_replaced [Boolean, nil]`: Whether a document was replaced.
+  # - `merge_containers [Boolean, nil]`: Whether containers should be merged.
+  # - `merged [Boolean, nil]`: Whether containers were merged.
+  #
+  # ## Usage Notes
+  # This model is used to parse and handle webhook responses from TrustID.
+  # Ensure that all fields are properly validated before use.
+  #
+  # ## References
+  # [TrustID API Documentation - WebhookResponse](https://developer.trustid.co.uk/documentation/ref/raw_ref/model/WebhookResponse.html)
+  class WebhookResponse < BaseModel
+    include HasNestedModels
+
+    # Define nested models
+    nested_model :callback, WebhookCallback
+
+    # Define all attributes
+    attribute :callback
+    attribute :response
+    attribute :access_denied, :boolean
+    attribute :callback_id, :string
+    attribute :locked, :boolean
+    attribute :message, :string
+    attribute :session_expired, :boolean
+    attribute :success, :boolean
+    attribute :vpe_unreachable, :boolean
+    attribute :auto_referred, :boolean
+    attribute :container_id, :string
+    attribute :document_replaced, :boolean
+    attribute :merge_containers, :boolean
+    attribute :merged, :boolean
+
+    # Helper methods for easy access to common properties
+    def operation_successful?
+      success == true
+    end
+
+    def container?
+      container_id.present?
+    end
+
+    def callback?
+      callback.present?
+    end
+
+    # Delegate common callback properties for convenience
+    def callback_container_id
+      callback&.container_id
+    end
+
+    def callback_document_id
+      callback&.document_id
+    end
+
+    def callback_client_application_reference
+      callback&.client_application_reference
+    end
+
+    def workflow_name
+      callback&.workflow_name
+    end
+
+    def workflow_state
+      callback&.workflow_state
+    end
+  end
+end

data/lib/trustid_sdk/models/workflow_storage_item.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'base_model'
+
+module TrustID
+  # WorkflowStorageItem
+  #
+  # Represents a single storage item in the workflow storage array.
+  # This model provides key-value storage for workflow state.
+  #
+  # Fields:
+  #   key   - String: The storage key
+  #   value - String: The storage value
+  #
+  # @see https://developer.trustid.co.uk/documentation/ref/raw_ref/model/WorkflowStorageItem.html
+  class WorkflowStorageItem < BaseModel
+    attribute :key, :string
+    attribute :value, :string
+
+    # Convert to hash representation
+    #
+    # @return [Hash] Hash representation of the storage item
+    def to_hash
+      {
+        key: key,
+        value: value
+      }
+    end
+
+    # Create instance from hash representation
+    #
+    # @param hash [Hash] Hash representation from to_hash
+    # @return [WorkflowStorageItem] New instance
+    def self.from_hash(hash)
+      return nil if hash.nil?
+
+      # Normalize keys to handle both original and generated formats
+      normalized_hash = hash.transform_keys do |key|
+        case key.to_s
+        when 'Key', 'key'
+          'key'
+        when 'Value', 'value'
+          'value'
+        else
+          key.to_s.underscore
+        end
+      end
+
+      new(normalized_hash)
+    end
+  end
+end

data/lib/trustid_sdk/models/workflow_type.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TrustID
+  # Represents the type of workflow a container is in as per TrustID API.
+  #
+  # This model provides constants representing possible workflow types
+  # and a utility method to retrieve the symbolic name for a given workflow type value.
+  #
+  # ## Enum Values
+  # - `STANDARD (0)`: Standard application workflow.
+  # - `AUTO_REFERRAL (1)`: Applications may be referred for manual inspection.
+  #
+  # ## Usage Notes
+  # Use the `name_for` method to retrieve the symbolic name for a given workflow type value.
+  #
+  # ## References
+  # [TrustID API Documentation - WorkflowType](https://developer.trustid.co.uk/documentation/ref/raw_ref/model/WorkflowType.html)
+  class WorkflowType
+    STANDARD = 0
+    AUTO_REFERRAL = 1
+
+    NAMES = {
+      STANDARD => 'Standard',
+      AUTO_REFERRAL => 'AutoReferral'
+    }.freeze
+
+    def self.name_for(value)
+      NAMES[value]
+    end
+  end
+end

data/lib/trustid_sdk/request.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module TrustID
+  class Request
+    def self.post(path, data)
+      client = TrustID.client
+      raise Errors::ClientError, 'Client not initialized' unless client
+
+      data = prepare_request_data(data, client)
+      uri = URI.join(client.server_url, path)
+      headers = prepare_headers
+
+      res = Net::HTTP.post(uri, data.to_json, headers)
+
+      handle_error(res) unless res.is_a?(Net::HTTPSuccess)
+
+      log_response(res) if TrustID.debug_mode
+
+      parse_response(res)
+    end
+
+    def self.get(path, params = {})
+      client = TrustID.client
+      raise Errors::ClientError, 'Client not initialized' unless client
+
+      uri = build_get_uri(client, path, params)
+      res = execute_get_request(uri)
+
+      handle_error(res) unless res.is_a?(Net::HTTPSuccess)
+
+      log_response(res) if TrustID.debug_mode
+
+      parse_response(res)
+    end
+
+    def self.build_get_uri(client, path, params)
+      uri = URI.join(client.server_url, path)
+      uri = URI.parse(uri.to_s) # Convert to URI object for query manipulation
+
+      query_params = prepare_query_params(params, client)
+      uri.query = URI.encode_www_form(query_params) unless query_params.empty?
+
+      uri
+    end
+
+    def self.prepare_query_params(params, client)
+      query_params = params.dup
+      query_params['DeviceId'] = client.device_id if client.device_id
+      query_params['SessionId'] = client.session_id if client.session_id
+      query_params
+    end
+
+    def self.execute_get_request(uri)
+      headers = prepare_get_headers
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+
+      req = Net::HTTP::Get.new(uri.request_uri, headers)
+      http.request(req)
+    end
+
+    def self.prepare_request_data(data, client)
+      data = data.merge('SessionId' => client.session_id) if client.session_id
+      data = data.merge('DeviceId' => client.device_id) if client.device_id
+      data
+    end
+
+    def self.prepare_headers
+      headers = { 'Content-Type' => 'application/json' }
+      config = TrustID.config
+      headers[config.api_header_key] = config.api_key if config.api_key
+      headers
+    end
+
+    def self.prepare_get_headers
+      headers = {}
+      config = TrustID.config
+      headers[config.api_header_key] = config.api_key if config.api_key
+      headers
+    end
+
+    def self.log_response(res)
+      puts "Response: #{res.body}"
+      puts "Response Code: #{res.code}"
+      puts "Response Headers: #{res.each_header.to_h}"
+    end
+
+    def self.parse_response(res)
+      content_type = res['Content-Type']
+      if content_type&.include?('application/json')
+        JSON.parse(res.body)
+      else
+        res.body
+      end
+    end
+
+    def self.handle_error(res)
+      case res
+      when Net::HTTPBadRequest
+        raise Errors::BadRequestError, res.body
+      when Net::HTTPUnauthorized
+        raise Errors::AuthenticationError, res.body
+      when Net::HTTPForbidden
+        raise Errors::AuthorizationError, res.body
+      when Net::HTTPNotFound
+        raise Errors::NotFoundError, res.body
+      else
+        raise Errors::ServerError, res.body
+      end
+    end
+  end
+end

data/lib/trustid_sdk/services/authentication.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TrustID
+  module Services
+    class Authentication
+      def initialize(username, password)
+        @username = username
+        @password = password
+        @client = TrustID.client
+      end
+
+      def login
+        response = Request.post('/VPE/session/login/', {
+                                  'Username' => @username,
+                                  'Password' => @password
+                                })
+        raise Errors::AuthenticationError, response, caller if response['AccessDenied']
+
+        @client.session_id = response['SessionId']
+      end
+    end
+  end
+end

data/lib/trustid_sdk/services/containers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TrustID
+  module Services
+    class Containers
+      # Fetch a container by ID (class-level convenience method)
+      def self.retrieve(container_id:)
+        new.retrieve(container_id:)
+      end
+
+      # Fetch a container by ID (instance-level method)
+      def retrieve(container_id:)
+        response = Request.post('/VPE/dataAccess/retrieveDocumentContainer/', {
+                                  'ContainerId' => container_id
+                                })
+        TrustID::Container.from_hash(response['Container'])
+      end
+    end
+  end
+end

data/lib/trustid_sdk/services/documents.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TrustID
+  require_relative '../models/document'
+
+  module Services
+    class Documents
+      # Fetch a document by ID (class-level convenience method)
+      def self.retrieve(container_id:, document_id:)
+        new.retrieve(container_id:, document_id:)
+      end
+
+      # Fetch a document by ID (instance-level method)
+      def retrieve(container_id:, document_id:)
+        response = Request.post('/VPE/dataAccess/retrieveDocument/', {
+                                  'ContainerId' => container_id,
+                                  'DocumentId' => document_id
+                                })
+        TrustID::Document.from_hash(response['Document'])
+      end
+    end
+  end
+end

data/lib/trustid_sdk/services/guest_links.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TrustID
+  module Services
+    class GuestLinks
+      def self.create(email:, name:)
+        new.create(email:, name:)
+      end
+
+      def create(email:, name:)
+        response = Request.post('/VPE/guestLink/createGuestLink/', {
+                                  'Email' => email,
+                                  'Name' => name
+                                })
+        TrustID::GuestLinkResponse.from_hash(response)
+      end
+    end
+  end
+end

data/lib/trustid_sdk/services/images.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TrustID
+  require_relative '../models/image'
+  module Services
+    class Images
+      # Fetch an image by ID (class-level convenience method)
+      def self.retrieve(image_id:)
+        new.retrieve(image_id:)
+      end
+
+      # Fetch an image by ID (instance-level method)
+      def retrieve(image_id:)
+        response = Request.post('/VPE/dataAccess/retrieveImage/', {
+                                  'ImageId' => image_id
+                                })
+        TrustID::Image.from_binary(response)
+      end
+    end
+  end
+end