davinci_crd_test_kit 0.13.0 → 0.14.0

data/lib/davinci_crd_test_kit/client/v2.2.1/verify_request/hook_request_requested_version_test.rb

@@ -0,0 +1,54 @@
+require_relative '../../multi_request_message_helper'
+require_relative '../../tagged_request_load_helper'
+
+module DaVinciCRDTestKit
+  module V221
+    class HookRequestRequestedVersionTest < Inferno::Test
+      include DaVinciCRDTestKit::MultiRequestMessageHelper
+      include DaVinciCRDTestKit::TaggedRequestLoadHelper
+
+      id :crd_v221_hook_request_requested_version
+      title 'Hook requests contains the CRD version extension'
+      description %(
+        Inferno's CRD service supports multiple versions of CRD, so [clients are required](https://hl7.org/fhir/us/davinci-crd/2.2.1/en/conformancedetails.html#ci-c-dev-3)
+        to specify the requested version using the `davinci-crd.requestedVersion` extension on each request.
+
+        During this test, Inferno will verify that the body of each hook request contains
+        the `davinci-crd.requestedVersion` extension with the correct value: "2.2".
+      )
+
+      verifies_requirements 'cds-hooks_3.0.0-ballot@214', 'hl7.fhir.us.davinci-crd_2.2.1@dev-3-A',
+                            'hl7.fhir.us.davinci-crd_2.2.1@dev-12'
+
+      run do
+        hook_requests = load_hook_requests
+
+        skip_if hook_requests.blank?, "No #{hook_name} hook requests received."
+
+        hook_requests.each_with_index do |request, request_index|
+          request_body = parse_json_request_entity(request.request_body, 'Request body', request_index)
+          next unless request_body.present?
+
+          requested_version = request_body.dig('extension', 'davinci-crd.requestedVersion')
+          if requested_version.blank?
+            add_request_message('error', "Required extension 'davinci-crd.requestedVersion' is not present.",
+                                request_index)
+          elsif !requested_version.is_a?(String)
+            add_request_message('error',
+                                "For extension 'davinci-crd.requestedVersion' expected a String, " \
+                                "got #{requested_version.class}",
+                                request_index)
+          elsif requested_version != '2.2'
+            add_request_message('error',
+                                "For extension 'davinci-crd.requestedVersion' expected '2.2', " \
+                                "got '#{requested_version}'",
+                                request_index)
+          end
+        end
+
+        assert_no_error_messages("#{requests_with_errors_prefix}Requested version extension not populated properly. " \
+                                 'See Messages for details.')
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.2.1/verify_request/hook_request_secured_transport_test.rb

@@ -0,0 +1,48 @@
+require_relative '../../multi_request_message_helper'
+require_relative '../../tagged_request_load_helper'
+
+module DaVinciCRDTestKit
+  module V221
+    class HookRequestSecuredTransportTest < Inferno::Test
+      include DaVinciCRDTestKit::MultiRequestMessageHelper
+      include DaVinciCRDTestKit::TaggedRequestLoadHelper
+
+      id :crd_v221_hook_request_secured_transport
+      title 'Hook request interactions use TLS'
+      description %(
+        During this test, Inferno will verify that
+        requests made by both the client and Inferno's simulated CRD servers are made against
+        TLS-secured endpoints using the `https` protocol.
+      )
+      verifies_requirements 'cds-hooks_3.0.0-ballot@2', 'cds-hooks_3.0.0-ballot@168', 'cds-hooks_3.0.0-ballot@172',
+                            'hl7.fhir.us.davinci-crd_2.2.1@sec-2'
+
+      run do
+        hook_requests = load_hook_requests
+
+        skip_if hook_requests.blank?, "No #{hook_name} hook requests received."
+
+        hook_requests.each_with_index do |request, request_index|
+          unless request.url.starts_with?('https')
+            add_request_message('error',
+                                "Inferno's simulated CRD server must use the https " \
+                                'protocol (TLS). Run this suite on a host that uses TLS.',
+                                request_index)
+          end
+
+          # check that the fhirServer endpoint uses https
+          request_body = parse_json_request_entity(request.request_body, 'Request body', request_index)
+          next unless request_body.present?
+          next unless request_body['fhirServer'].present? && !request_body['fhirServer'].starts_with?('https')
+
+          add_request_message('error',
+                              'The `fhirServer` provided in the request must use the https protocol (TLS).',
+                              request_index)
+        end
+
+        assert_no_error_messages("#{requests_with_errors_prefix}Interactions not secured using TLS. " \
+                                 'See Messages for details.')
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.2.1/verify_response/client_display_cards_attest.rb

@@ -0,0 +1,74 @@
+require_relative '../client_urls'
+require_relative '../../../cross_suite/cards_identification'
+require_relative '../../tagged_request_load_helper'
+
+module DaVinciCRDTestKit
+  module V221
+    class ClientCardDisplayAttest < Inferno::Test
+      include ClientURLs
+      include CardsIdentification
+      include DaVinciCRDTestKit::TaggedRequestLoadHelper
+
+      id :crd_v221_card_display_attest_test
+      title 'Client displays returned decision support details to the user (Attestation)'
+      description %(
+        During this test, the tester will confirm that the received cards and actions in the
+        hook responses have been displayed or otherwise made available to users of the client system
+        in an appopriate way that allows for consideration and action if warranted.
+      )
+
+      def responded_card_types
+        list_card_types_in_requests(requests)
+      end
+
+      def format_responded_response_types
+        responded_card_types
+          .map do |response_type|
+          response_type_string =
+            response_type.split('_')
+              .map(&:capitalize)
+              .join(' ')
+              .prepend('- ')
+              .sub('Smart', 'SMART')
+              .sub('Create Update', 'Create/Update')
+              .sub('Companions Prerequisites', 'Companions/Prerequisites')
+              .sub('Card', '(card)')
+              .sub('Action', '(systemAction)')
+          response_type_string
+        end
+          .join("\n")
+      end
+
+      output :attest_true_url
+      output :attest_false_url
+
+      run do
+        load_hook_requests
+        skip_if responded_card_types.blank?, 'No responses sent to the client.'
+
+        identifier = SecureRandom.hex(32)
+        attest_true_url = "#{resume_pass_url}?token=#{identifier}"
+        attest_false_url = "#{resume_fail_url}?token=#{identifier}"
+        output(attest_true_url:)
+        output(attest_false_url:)
+        wait(
+          identifier:,
+          message: <<~MESSAGE
+            **Card Display Attestation**:
+
+            I attest that the following CRD response types returned by Inferno's simulated
+            CRD servers were processed by the client system and displayed or otherwise made
+            available to users of the client system in an appropriate way that allows for
+            consideration and action if warranted:
+
+            #{format_responded_response_types}
+
+            [Click here](#{attest_true_url}) if the above statement is **true**.
+
+            [Click here](#{attest_false_url}) if the above statement is **false**.
+          MESSAGE
+        )
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.2.1/verify_response/hook_response_support_coverage_information_test.rb

@@ -0,0 +1,30 @@
+require_relative '../../../cross_suite/cards_identification'
+require_relative '../../tagged_request_load_helper'
+
+module DaVinciCRDTestKit
+  module V221
+    class ClientHookResponseSupportCoverageInformationTest < Inferno::Test
+      include CardsIdentification
+      include TaggedRequestLoadHelper
+
+      title 'Client supports the Coverage Information response type on this hook'
+      id :crd_v221_client_hook_response_support_coverage_information
+      description <<~DESCRIPTION
+        During this test, Inferno will verify that the client demonstrated support for the [Coverage Information](https://hl7.org/fhir/us/davinci-crd/2.2.1/en/cards.html#coverage-information)
+        response type. At least one hook invocation performed during this group must have returned a Coverage Information action.
+
+        If this test fails, adjust the [cards returned by Inferno's simulated CRD server](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses)
+        and/or the hook requests made by the client during this group such that a Coverage Information action is returned.
+      DESCRIPTION
+
+      run do
+        hook_requests = load_hook_requests
+        skip_if hook_requests.blank?, "No #{hook_name} hook requests received."
+
+        sorted_cards = sorted_cards_from_requests(hook_requests)
+        assert sorted_cards['actions'][COVERAGE_INFORMATION_RESPONSE_TYPE].present?,
+               "Support for the Coverage Information response type not demonstrated for the #{hook_name} hook."
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/client/v2.2.1/verify_response/inferno_response_validation.rb

@@ -0,0 +1,77 @@
+require_relative '../../../cross_suite/cards_validation'
+require_relative '../../../cross_suite/response_logical_model_validation'
+require_relative '../../tagged_request_load_helper'
+
+module DaVinciCRDTestKit
+  module V221
+    class InfernoResponseValidationTest < Inferno::Test
+      include CardsValidation
+      include ResponseLogicalModelValidation
+      include DaVinciCRDTestKit::TaggedRequestLoadHelper
+
+      title 'Hook responses have the correct structure and content'
+      description %(
+        During this test, Inferno will verify that each hook response built by Inferno's simulated CRD servers
+        and returned to the client conforms to CDS Hooks and CRD requirements. These responses must be conformant
+        for the client to demonstrate its ability to accept and process valid CRD responses.
+
+        If this test fails when the tester provided a custom response template, adjust the
+        provided template and the submitted requests so that the response built by Inferno
+        is conformant. If this test fails when Inferno mocked the response based on selected
+        card types, first ensure that the client's request is conformant. If the request is conformant
+        but Inferno's response(s) are still not conformant, please report this failure to the
+        Inferno team via [GitHub Issues](https://github.com/inferno-framework/davinci-crd-test-kit/issues).
+        For more details on how Inferno builds responses, see the
+        [Controlling Simulated Responses](https://github.com/inferno-framework/davinci-crd-test-kit/wiki/Controlling-Simulated-Responses)
+        section of the [CRD Test Kit Wiki](https://github.com/inferno-framework/davinci-crd-test-kit/wiki).
+      )
+      id :crd_v221_inferno_response_validation
+      simulation_verification
+
+      verifies_requirements 'cds-hooks_3.0.0-ballot@3', 'cds-hooks_3.0.0-ballot@222', 'cds-hooks_3.0.0-ballot@223',
+                            'cds-hooks_3.0.0-ballot@224'
+
+      input :custom_response_template, optional: true
+
+      def response_label(index = nil)
+        response_type = (custom_response_template.present? ? 'Custom built' : 'Mocked')
+        "#{response_type} response#{" #{index}" if index.present?}"
+      end
+
+      def validate_card_summaries(cards)
+        return unless cards.is_a?(Array)
+
+        cards.each { |card| card_summary_check(card) if card.is_a?(Hash) }
+      end
+
+      run do
+        load_hook_requests
+
+        skip_if request.blank?, "No #{response_label.downcase}s to verify."
+
+        entity_validated = false
+        requests.each_with_index do |request, index|
+          response_hash = JSON.parse(request.response_body)
+          request_hash = JSON.parse(request.request_body)
+
+          next unless response_hash['cards'].present? || response_hash['systemActions'].present?
+
+          entity_validated = true
+          validate_card_summaries(response_hash['cards'])
+          perform_response_logical_model_validation(response_hash['cards'],
+                                                    response_hash['systemActions'],
+                                                    request_hash,
+                                                    index,
+                                                    '2.2.1')
+        rescue JSON::ParserError
+          next
+        end
+
+        skip_if !entity_validated,
+                "No #{response_label.downcase} cards or system actions to verify returned by Inferno."
+
+        no_error_validation("Invalid Inferno #{response_label.downcase}(s). See Messages for details.")
+      end
+    end
+  end
+end

data/lib/davinci_crd_test_kit/cross_suite/base_urls.rb

@@ -0,0 +1,20 @@
+module DaVinciCRDTestKit
+  RESUME_PASS_PATH = '/resume_pass'.freeze
+  RESUME_FAIL_PATH = '/resume_fail'.freeze
+
+  # base url, plus other shared ones such as resume urls
+  # suite_id must be defined
+  module BaseURLs
+    def inferno_base_url
+      @inferno_base_url ||= "#{Inferno::Application['base_url']}/custom/#{suite_id}"
+    end
+
+    def resume_pass_url
+      @resume_pass_url ||= inferno_base_url + RESUME_PASS_PATH
+    end
+
+    def resume_fail_url
+      @resume_fail_url ||= inferno_base_url + RESUME_FAIL_PATH
+    end
+  end
+end

data/lib/davinci_crd_test_kit/cross_suite/cards_identification.rb

@@ -0,0 +1,312 @@
+require_relative 'hook_request_field_validation'
+require_relative 'suggestion_actions_validation'
+
+module DaVinciCRDTestKit
+  module CardsIdentification
+    include DaVinciCRDTestKit::SuggestionActionsValidation
+    include DaVinciCRDTestKit::HookRequestFieldValidation
+
+    COVERAGE_INFO_EXT_URL = 'http://hl7.org/fhir/us/davinci-crd/StructureDefinition/ext-coverage-information'.freeze
+
+    ADDITIONAL_ORDERS_RESPONSE_TYPE = 'companions_prerequisites'.freeze
+    COVERAGE_INFORMATION_RESPONSE_TYPE = 'coverage_information'.freeze
+    CREATE_OR_UPDATE_COVERAGE_RESPONSE_TYPE = 'create_update_coverage_info'.freeze
+    EXTERNAL_REFERENCE_RESPONSE_TYPE = 'external_reference'.freeze
+    FORM_COMPLETION_RESPONSE_TYPE = 'request_form_completion'.freeze
+    INSTRUCTIONS_RESPONSE_TYPE = 'instructions'.freeze
+    LAUNCH_SMART_APP_RESPONSE_TYPE = 'launch_smart_app'.freeze
+    PROPOSE_ALTERNATIVE_REQUEST_RESPONSE_TYPE = 'propose_alternate_request'.freeze
+    COVERAGE_INFO_CONFIGURATION_CODE = 'coverage-info'.freeze
+
+    ADDITIONAL_ORDERS_EXPECTED_RESOURCE_TYPES = %w[
+      CommunicationRequest Device DeviceRequest Medication
+      MedicationRequest NutritionOrder ServiceRequest
+      VisionPrescription
+    ].freeze
+
+    PROPOSE_ALTERNATIVE_REQUEST_EXPECTED_RESOURCE_TYPES = %w[
+      CommunicationRequest Device DeviceRequest Encounter Medication
+      MedicationRequest NutritionOrder ServiceRequest
+      VisionPrescription
+    ].freeze
+
+    COVERAGE_INFO_EXPECTED_RESOURCE_TYPES = %w[
+      Appointment CommunicationRequest DeviceRequest Encounter MedicationRequest
+      NutritionOrder ServiceRequest VisionPrescription
+    ].freeze
+
+    def identify_card_type(card) # rubocop:disable Metrics/CyclomaticComplexity
+      return nil if card['type'].present? # action, not a card
+      return ADDITIONAL_ORDERS_RESPONSE_TYPE if additional_orders_response_type?(card)
+      return CREATE_OR_UPDATE_COVERAGE_RESPONSE_TYPE if create_or_update_coverage_card_response_type?(card)
+      return EXTERNAL_REFERENCE_RESPONSE_TYPE if external_reference_response_type?(card)
+      return FORM_COMPLETION_RESPONSE_TYPE if form_completion_card_response_type?(card)
+      return INSTRUCTIONS_RESPONSE_TYPE if instructions_response_type?(card)
+      return LAUNCH_SMART_APP_RESPONSE_TYPE if launch_smart_app_response_type?(card)
+      return PROPOSE_ALTERNATIVE_REQUEST_RESPONSE_TYPE if propose_alternative_request_response_type?(card)
+
+      nil
+    end
+
+    def identify_action_type(action)
+      return nil unless action['type'].present? # card, not an action
+      return COVERAGE_INFORMATION_RESPONSE_TYPE if coverage_information_response_type?(action)
+      return CREATE_OR_UPDATE_COVERAGE_RESPONSE_TYPE if create_or_update_coverage_action_response_type?(action)
+      return FORM_COMPLETION_RESPONSE_TYPE if form_completion_action_response_type?(action)
+
+      nil
+    end
+
+    def coverage_info_card_type?(card)
+      return false unless card.respond_to?(:dig)
+
+      card.dig('source', 'topic', 'code') == COVERAGE_INFO_CONFIGURATION_CODE
+    end
+
+    def coverage_info_system_action_type?(action)
+      return false unless action.respond_to?(:[])
+
+      [COVERAGE_INFORMATION_RESPONSE_TYPE, FORM_COMPLETION_RESPONSE_TYPE].include?(identify_action_type(action))
+    end
+
+    def coverage_info_content(response_body)
+      return [[], []] unless response_body.is_a?(Hash)
+
+      cards =
+        if response_body['cards'].is_a?(Array)
+          response_body['cards'].select { |card| coverage_info_card_type?(card) }
+        else
+          []
+        end
+      actions =
+        if response_body['systemActions'].is_a?(Array)
+          response_body['systemActions'].select { |action| coverage_info_system_action_type?(action) }
+        else
+          []
+        end
+
+      [cards, actions]
+    end
+
+    def coverage_info_response?(response_body)
+      cards, actions = coverage_info_content(response_body)
+
+      cards.present? || actions.present?
+    end
+
+    def coverage_info_configuration_disabled?(request_body)
+      request_body.is_a?(Hash) &&
+        request_body.dig('extension', 'davinci-crd.configuration', COVERAGE_INFO_CONFIGURATION_CODE) == false
+    end
+
+    def disable_coverage_info_configuration!(request_body)
+      request_body['extension'] = {} unless request_body['extension'].is_a?(Hash)
+      unless request_body['extension']['davinci-crd.configuration'].is_a?(Hash)
+        request_body['extension']['davinci-crd.configuration'] = {}
+      end
+      request_body['extension']['davinci-crd.configuration'][COVERAGE_INFO_CONFIGURATION_CODE] = false
+
+      request_body
+    end
+
+    def additional_orders_response_type?(card, expected_resource_types: ADDITIONAL_ORDERS_EXPECTED_RESOURCE_TYPES)
+      return false if card['suggestions'].blank?
+
+      card['suggestions'].all? do |suggestion|
+        actions = suggestion['actions']
+        actions&.all? do |action|
+          action['type'] == 'create' &&
+            (expected_resource_types.blank? || action_resource_type_check(action, expected_resource_types))
+        end
+      end
+    end
+
+    def coverage_information_response_type?(action) # rubocop:disable Metrics/CyclomaticComplexity
+      return false unless action.respond_to?(:[])
+
+      resource = action['resource']&.to_hash
+      return false unless COVERAGE_INFO_EXPECTED_RESOURCE_TYPES.include? resource&.dig('resourceType')
+
+      unless resource&.dig('extension')&.any? { |extension| extension_url(extension) == COVERAGE_INFO_EXT_URL }
+        return false
+      end
+
+      true
+    end
+
+    def extension_url(extension)
+      return extension.url if extension.respond_to?(:url)
+      return extension['url'] if extension.respond_to?(:[])
+
+      nil
+    end
+
+    def create_or_update_coverage_card_response_type?(card)
+      card['suggestions']&.one? && card['suggestions'].first['actions']&.one? do |action|
+        create_or_update_coverage_action_response_type?(action)
+      end
+    end
+
+    def create_or_update_coverage_action_response_type?(action)
+      ['create', 'update'].include?(action['type']) && action_resource_type_check(action, ['Coverage'])
+    end
+
+    def create_questionnaire_action_response_type?(action)
+      action['type'] == 'create' && action_resource_type_check(action, ['Questionnaire'])
+    end
+
+    def external_reference_response_type?(card)
+      links = card['links']
+      return false if links.blank?
+
+      links.all? { |link| link['type'] == 'absolute' }
+    end
+
+    def form_completion_card_response_type?(card)
+      card['suggestions']&.all? do |suggestion|
+        suggestion['actions']&.one? { |action| form_completion_action_response_type?(action) }
+      end
+    end
+
+    def form_completion_action_response_type?(action)
+      action['type'] == 'create' &&
+        action_resource_type_check(action, ['Task']) &&
+        form_completion_task_questionnaire?(action['resource'])
+    end
+
+    def form_completion_task_questionnaire?(task_action)
+      task_action.dig('code', 'coding')&.any? { |code| code['code'] == 'complete-questionnaire' } &&
+        task_action['input']&.any? do |input|
+          input.dig('type', 'text') == 'questionnaire' && valid_url?(input['valueCanonical'])
+        end
+    end
+
+    def instructions_response_type?(card)
+      card['links'].blank? && card['suggestions'].blank?
+    end
+
+    def launch_smart_app_response_type?(card)
+      links = card['links']
+      return false if links.blank?
+
+      links.all? { |link| link['type'] == 'smart' }
+    end
+
+    def propose_alternative_request_response_type?(
+      card,
+      expected_resource_types: PROPOSE_ALTERNATIVE_REQUEST_EXPECTED_RESOURCE_TYPES
+    )
+      card['suggestions']&.any? do |suggestion|
+        actions = suggestion['actions']
+        has_update = check_action_type(actions, 'update', expected_resource_types)
+        has_delete = check_action_type(actions, 'delete', expected_resource_types)
+        has_create = check_action_type(actions, 'create', expected_resource_types)
+
+        has_update || (has_delete && has_create)
+      end
+    end
+
+    def check_action_type(actions, action_type, expected_resource_types)
+      actions&.any? do |action|
+        action['type'] == action_type &&
+          (expected_resource_types.blank? || action_resource_type_check(action, expected_resource_types))
+      end
+    end
+
+    def list_card_types_in_requests(hooks_requests)
+      sorted_cards = sorted_cards_from_requests(hooks_requests)
+
+      present_card_types = sorted_cards['cards'].select { |key, value| key.present? && value.present? }.keys
+      present_action_types = sorted_cards['actions'].select { |key, value| key.present? && value.present? }.keys
+
+      present_card_types.map { |type| "#{type}_card" } + present_action_types.map { |type| "#{type}_action" }
+    end
+
+    def sorted_cards_from_requests(hooks_requests)
+      return sorted_cards_from_cache if sorted_cards_cached?(hooks_requests)
+
+      sorted_cards = initialize_sorted_cards_hash
+
+      hooks_requests.each do |request|
+        sort_card_types_from_request(request, sorted_cards)
+      rescue JSON::ParserError
+        next
+      end
+
+      cache_sorted_cards(hooks_requests, sorted_cards)
+      sorted_cards
+    end
+
+    def sort_card_types_from_request(request, sorted_cards)
+      response_body = JSON.parse(request.response_body)
+      response_body['cards']&.each do |card|
+        sorted_cards['cards'][identify_card_type(card)] << card
+      end
+
+      response_body['systemActions']&.each do |action|
+        sorted_cards['actions'][identify_action_type(action)] << action
+      end
+    end
+
+    def initialize_sorted_cards_hash
+      {
+        'cards' => {
+          ADDITIONAL_ORDERS_RESPONSE_TYPE => [],
+          CREATE_OR_UPDATE_COVERAGE_RESPONSE_TYPE => [],
+          EXTERNAL_REFERENCE_RESPONSE_TYPE => [],
+          FORM_COMPLETION_RESPONSE_TYPE => [],
+          INSTRUCTIONS_RESPONSE_TYPE => [],
+          LAUNCH_SMART_APP_RESPONSE_TYPE => [],
+          PROPOSE_ALTERNATIVE_REQUEST_RESPONSE_TYPE => [],
+          nil => [] # unknown type
+        },
+        'actions' => {
+          COVERAGE_INFORMATION_RESPONSE_TYPE => [],
+          CREATE_OR_UPDATE_COVERAGE_RESPONSE_TYPE => [],
+          FORM_COMPLETION_RESPONSE_TYPE => [],
+          nil => [] # unknown type
+        }
+      }
+    end
+
+    def extract_coverage_information_extensions(sorted_cards)
+      coverage_information_extensions = []
+
+      sorted_cards['actions'][COVERAGE_INFORMATION_RESPONSE_TYPE].each do |coverage_information_action|
+        coverage_information_action['resource']['extension'].each do |extension|
+          coverage_information_extensions << extension if extension['url'] == COVERAGE_INFO_EXT_URL
+        end
+      end
+
+      coverage_information_extensions.map { |ext| FHIR::Extension.new(ext) }
+    end
+
+    def sorted_cards_cached?(requests)
+      return false unless scratch['sorted_cards'].present?
+      return false unless scratch['sorted_cards']['hook_instances'].length == requests.length
+
+      requests.all? do |request|
+        scratch['sorted_cards']['hook_instances'].include?(JSON.parse(request.request_body)&.dig('hookInstance'))
+      rescue JSON::ParserError
+        false
+      end
+    end
+
+    def cache_sorted_cards(requests, sorted_cards)
+      scratch['sorted_cards'] = {
+        'hook_instances' => hook_instances_from_requests(requests),
+        'data' => sorted_cards
+      }
+    rescue JSON::ParserError
+      nil
+    end
+
+    def sorted_cards_from_cache
+      scratch['sorted_cards']['data']
+    end
+
+    def hook_instances_from_requests(requests)
+      requests.map { |request| JSON.parse(request.request_body)&.dig('hookInstance') }.compact
+    end
+  end
+end