hln_ice 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 693ce96464262bed3bdbba9a9d38cc91aaaba9620c270e49994b4c0537c21b4d
-  data.tar.gz: 74711ef35d3caf83aa5b210ad0665b152275224fbc571349b686432d0fed0e10
+  metadata.gz: 80a72761b4c53974d8784c926ca86d27953488ac8c6e99e9bdb386447b8a3f98
+  data.tar.gz: 3952414a0bf97c45cc2a7009c4b16b1a016bb866697821c1bf69c1b60bcc05ac
 SHA512:
-  metadata.gz: 6f47f5f31184385ebf20e319a415720094a792fe2e91b3e35218771e7ff15f80ecac1956771eab2bbd773c820ae2e54b5df6dc774f1bffc97786ad7814419918
-  data.tar.gz: ac317607ab177277cba5c32c458d3f5ddb583a6e84f0e98ab70d774128986db2c393d1a2d783f50386d93ae74ad0800967443024f20a93cd5f6e0a9eedaa9405
+  metadata.gz: 2389561c18f1c9d88f486214bf4bcd5eb6b9b3bc92f08b08fc7d6ac360ccc07360646cece3ddde6c26c5a6a5dddb2026bea28f211ce5f700ace3f1baad4179c8
+  data.tar.gz: bd197b89a993c6df99f2fad1d586a3da4ce31715388a541f4679ad96a26c2c9635cdebeeef502ba67808fbbb9427c14338bc9fcd0692ca9a84f9ef242128761c

data/.rubocop.yml

@@ -1,5 +1,8 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
   TargetRubyVersion: 3.1
+  SuggestExtensions: false
 
 Style/StringLiterals:
   Enabled: true
@@ -11,3 +14,15 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+# Methods after `private` are indented one level, Rails style.
+Layout/IndentationConsistency:
+  EnforcedStyle: indented_internal_methods
+
+# With indented private methods, `private` is followed directly by them.
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/.rubocop_todo.yml

@@ -0,0 +1,43 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --no-auto-gen-timestamp`
+# using RuboCop version 1.91.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 5
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 70
+
+# Offense count: 2
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 50
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 113
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+# Offense count: 8
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 72
+
+# Offense count: 1
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 6
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 15

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-06
+
+- Expose ICE's per-dose evaluations under `evaluations` in the result, with one entry per administered dose and vaccine group it counts toward (so a combination vaccine has several). Each entry has the caller's event id, CVX, administration date, vaccine group, dose number, validity, evaluation status, and reasons. Codes are passed through as ICE returns them. `recommendations` and `simplified_status` are unchanged.
+
+## [0.3.0] - 2026-09-24
+
+- Expose schedule authorities (e.g. `ACIP_CDC`, `AAP`, `AAFP`) on each recommendation under `schedule_authorities` when the ICE server has `outputScheduleAuthorities` enabled. The key is omitted when the server does not return them.
+- Fix recommendations being silently dropped when a proposal's schedule authorities observation precedes its status observation.
+
 ## [0.2.0] - 2026-07-02
 
 - Stop logging PHI by default. The ICE input data, generated request XML, and raw service response are no longer logged unless the new `log_payloads:` option is set to `true`. Warnings and errors are still logged.

data/README.md

@@ -6,7 +6,8 @@ Given a patient's demographics and immunization history, `HlnIce` builds the
 VMR (Virtual Medical Record) request, calls the ICE evaluation endpoint, and
 parses the response into:
 
-- a full list of **recommendations** (one per vaccine group, with status, reasons, and administration intervals), and
+- a full list of **recommendations** (one per vaccine group, with status, reasons, and administration intervals),
+- the **evaluations** of each administered dose (per vaccine group, with dose number, validity, and reasons), and
 - a **simplified status** map keyed by vaccine group — e.g. `{ ipv_opv: "overdue", mmr: "compliant" }`.
 
 The gem has no Rails or ActiveSupport dependency; it takes an injected logger
@@ -79,6 +80,7 @@ patient_data = {
       clinicalStatements: {
         substanceAdministrationEvents: [
           {
+            id: "1", # echoed back as event_id on evaluations; a UUID is generated if omitted
             substance: {
               substanceCode: { code: "10", displayName: "Polio" }
             },
@@ -108,7 +110,26 @@ On success:
         vaccine: { code: "10", code_system: "...", name: "Polio Vaccine Group" },
         status:  { code: "RECOMMENDED", name: "Recommended" },
         reasons: [{ code: "DUE_NOW", name: "Due Now" }],
-        intervals: { proposed: { low: "2020-03-01", high: "2020-04-01" } }
+        intervals: { proposed: { low: "2020-03-01", high: "2020-04-01" } },
+        # Only present when the ICE server has outputScheduleAuthorities enabled
+        schedule_authorities: [
+          { code: "ACIP_CDC", name: "Advisory Committee on Immunization Practices / Centers for Disease Control and Prevention" },
+          { code: "AAP", name: "American Academy of Pediatrics" }
+        ]
+      }
+    ],
+    # One entry per administered dose and vaccine group it counts toward, so a
+    # combination vaccine has several. Codes are passed through from ICE.
+    evaluations: [
+      {
+        event_id: "1",
+        cvx: "10",
+        administered_on: "2020-03-01",
+        vaccine_group: { code: "400", name: "Polio Vaccine Group" },
+        dose_number: 1, # nil if ICE omits it
+        valid: true,
+        status: { code: "VALID", name: "Valid Dose" }, # e.g. VALID, INVALID, ACCEPTED
+        reasons: [] # e.g. [{ code: "BELOW_MINIMUM_INTERVAL", name: "Below Minimum Interval" }]
       }
     ],
     simplified_status: { ipv_opv: "overdue" }

data/lib/hln_ice/client.rb

@@ -1,12 +1,8 @@
 # frozen_string_literal: true
 
-require "date"
 require "json"
-require "base64"
 require "logger"
-require "securerandom"
 require "httparty"
-require "nokogiri"
 
 module HlnIce
   # Client for the HLN ICE (Immunization Calculation Engine) OpenCDS service.
@@ -14,28 +10,12 @@ module HlnIce
   # Evaluates a patient's immunization history against the ICE forecasting
   # rules and returns both the raw recommendations and a simplified status
   # mapping keyed by vaccine group.
+  #
+  # All logging happens here: RequestBuilder and ResponseParser never log, so
+  # this class is the only place that can write patient data to the logs.
   class Client
-    # Mapping from ICE status codes to our status keys
-    STATUS_MAPPING = {
-      "CONDITIONAL" => "conditional",
-      "FUTURE_RECOMMENDED" => "compliant",
-      "NOT_RECOMMENDED" => "compliant",
-      "RECOMMENDED" => "overdue",
-    }.freeze
-
-    # Mapping from ICE vaccine groups to our immunization keys
-    VACCINE_MAPPING = {
-      "DTP Vaccine Group" => :dtap_tdap,
-      "Hep A Vaccine Group" => :hep_a,
-      "Hep B Vaccine Group" => :hep_b,
-      "Hib Vaccine Group" => :hib,
-      "HPV Vaccine Group" => :hpv,
-      "Meningococcal Vaccine Group" => :mcv4,
-      "MMR Vaccine Group" => :mmr,
-      "Pneumococcal Vaccine Group" => :pcv,
-      "Polio Vaccine Group" => :ipv_opv,
-      "Varicella Vaccine Group" => :var,
-    }.freeze
+    STATUS_MAPPING = SimplifiedStatus::STATUS_MAPPING
+    VACCINE_MAPPING = SimplifiedStatus::VACCINE_MAPPING
 
     attr_reader :base_url, :timeout, :max_retries, :retry_delay, :logger, :log_payloads
 
@@ -62,7 +42,7 @@ module HlnIce
         )
 
         response.success?
-      rescue => e
+      rescue StandardError => e
         logger.error("ICE service unavailable: #{e.message}")
         false
       end
@@ -95,7 +75,7 @@ module HlnIce
         else
           handle_error_response(response)
         end
-      rescue => e
+      rescue StandardError => e
         retries += 1
         if retries <= max_retries
           logger.warn("Retrying ICE request (#{retries}/#{max_retries}): #{e.message}")
@@ -109,157 +89,24 @@ module HlnIce
     end
 
     private
-      # Plain-Ruby equivalent of ActiveSupport's `blank?`.
-      def blank?(value)
-        return true if value.nil?
-        return value.strip.empty? if value.is_a?(String)
-        return value.empty? if value.respond_to?(:empty?)
-
-        false
-      end
-
-      # Plain-Ruby equivalent of ActiveSupport's `present?`.
-      def present?(value)
-        !blank?(value)
-      end
-
       def build_ice_payload(patient_data)
-        # Extract patient information
-        patient_id = patient_data[:patient][:id]
-        date_of_birth = patient_data[:patient][:date_of_birth]
-        gender = patient_data[:patient][:gender]
-        gender = "U" if blank?(gender) # Set default to 'U' if blank
+        builder = RequestBuilder.new(patient_data)
 
         # Log input data for debugging
         logger.debug("ICE Input Data: #{JSON.pretty_generate(patient_data)}") if log_payloads
 
-        # Build the VMR XML
-        xml_payload = <<~XML
-          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-          <ns4:cdsInput xmlns:ns2="org.opencds"
-                        xmlns:ns3="org.opencds.vmr.v1_0.schema.vmr"
-                        xmlns:ns4="org.opencds.vmr.v1_0.schema.cdsinput"
-                        xmlns:ns5="org.opencds.vmr.v1_0.schema.cdsoutput">
-            <templateId root="2.16.840.1.113883.3.795.11.1.1"/>
-            <cdsContext>
-              <cdsSystemUserPreferredLanguage code="en" codeSystem="2.16.840.1.113883.6.99" displayName="English"/>
-            </cdsContext>
-            <vmrInput>
-              <templateId root="2.16.840.1.113883.3.795.11.1.1"/>
-              <patient>
-                <templateId root="2.16.840.1.113883.3.795.11.2.1.1"/>
-                <id root="2.16.840.1.113883.3.795.12.100.11" extension="#{patient_id}"/>
-                <demographics>
-                  <birthTime value="#{format_date_for_ice(date_of_birth)}"/>
-                  <gender code="#{gender}" codeSystem="2.16.840.1.113883.5.1"/>
-                </demographics>
-                <clinicalStatements>
-                  <substanceAdministrationEvents>
-        XML
-
-        # Add immunization records if available
-        if present?(patient_data[:immunizations])
-          patient_data[:immunizations].each do |imm|
-            next unless present?(imm.dig(:clinicalStatements, :substanceAdministrationEvents))
-
-            imm[:clinicalStatements][:substanceAdministrationEvents].each do |event|
-              next unless present?(event.dig(:substance, :substanceCode))
-
-              substance_code = event[:substance][:substanceCode]
-
-              # Format dates to ICE format (YYYYMMDD)
-              low_date = format_date_for_ice(event[:administrationTimeInterval][:low])
-              high_date = format_date_for_ice(event[:administrationTimeInterval][:high])
-
-              xml_payload += <<~XML
-                    <substanceAdministrationEvent>
-                      <templateId root="2.16.840.1.113883.3.795.11.9.1.1"/>
-                      <id root="#{event[:id] || SecureRandom.uuid}"/>
-                      <substanceAdministrationGeneralPurpose code="384810002" codeSystem="2.16.840.1.113883.6.5"/>
-                      <substance>
-                        <id root="#{event[:substance][:id] || SecureRandom.uuid}"/>
-                        <substanceCode code="#{substance_code[:code]}"
-                                    codeSystem="2.16.840.1.113883.12.292"
-                                    displayName="#{substance_code[:displayName]}"
-                                    originalText="#{substance_code[:displayName]}"/>
-                      </substance>
-                      <administrationTimeInterval low="#{low_date}" high="#{high_date}"/>
-                    </substanceAdministrationEvent>
-              XML
-            end
-          end
-        end
-
-        # Close the XML
-        xml_payload += <<~XML
-                  </substanceAdministrationEvents>
-                </clinicalStatements>
-              </patient>
-            </vmrInput>
-          </ns4:cdsInput>
-        XML
-
         # Log the generated XML for debugging
-        logger.debug("Generated ICE XML: #{xml_payload}") if log_payloads
+        logger.debug("Generated ICE XML: #{builder.xml}") if log_payloads
 
-        # Base64 encode the XML
-        base64_encoded_payload = Base64.strict_encode64(xml_payload)
-
-        # Build the full payload
-        {
-          "interactionId" => {
-            "scopingEntityId" => "org.nyc.cir",
-            "interactionId" => "#{patient_id}-#{Time.now.to_i}",
-            "submissionTime" => (Time.now.to_f * 1000).to_i
-          },
-          "evaluationRequest" => {
-            "clientLanguage" => "en",
-            "clientTimeZoneOffset" => "+0000",
-            "kmEvaluationRequest" => [
-              {
-                "kmId" => {
-                  "scopingEntityId" => "org.nyc.cir",
-                  "businessId" => "ICE",
-                  "version" => "1.0.0"
-                }
-              }
-            ],
-            "dataRequirementItemData" => [
-              {
-                "driId" => {
-                  "containingEntityId" => {
-                    "scopingEntityId" => "org.nyc.cir",
-                    "businessId" => "ICEData",
-                    "version" => "1.0.0"
-                  },
-                  "itemId" => "cdsPayload"
-                },
-                "data" => {
-                  "informationModelSSId" => {
-                    "scopingEntityId" => "org.opencds.vmr",
-                    "businessId" => "VMR",
-                    "version" => "1.0"
-                  },
-                  "base64EncodedPayload" => [base64_encoded_payload]
-                }
-              }
-            ]
-          }
-        }
+        builder.payload
       end
 
       def parse_ice_response(response_body)
         logger.debug("ICE service response: #{response_body}") if log_payloads
 
-        result = JSON.parse(response_body)
-
-        if result.dig("finalKMEvaluationResponse", 0, "kmEvaluationResultData", 0, "data", "base64EncodedPayload", 0)
-          base64_result = result["finalKMEvaluationResponse"][0]["kmEvaluationResultData"][0]["data"]["base64EncodedPayload"][0]
-          decoded_result = Base64.decode64(base64_result)
-
-          # Parse the XML response
-          parsed_result = parse_xml_response(decoded_result)
+        parsed_result = ResponseParser.new(response_body).data
 
+        if parsed_result
           {
             success: true,
             data: parsed_result
@@ -271,189 +118,23 @@ module HlnIce
             error: "No valid response found in ICE output."
           }
         end
-      rescue => e
+      rescue StandardError => e
         logger.error("Error parsing ICE response: #{e.message}")
         { success: false, error: "Error parsing ICE response: #{e.message}" }
       end
 
-      def parse_xml_response(xml_string)
-        # Parse the XML
-        doc = Nokogiri::XML(xml_string)
-
-        # Remove namespaces to simplify parsing
-        doc.remove_namespaces!
-
-        # Extract patient information
-        patient = doc.xpath("//patient").first
-        return { raw_xml: xml_string } unless patient
-
-        patient_id = patient.xpath("./id").first["extension"] rescue nil
-        birth_time = patient.xpath("./demographics/birthTime").first["value"] rescue nil
-        gender = patient.xpath("./demographics/gender").first["code"] rescue nil
-
-        # Format birth date if present
-        birth_date = format_ice_date(birth_time)
-
-        # Extract vaccine recommendations
-        all_recommendations = []
-
-        doc.xpath("//substanceAdministrationProposal").each do |proposal|
-          # Get the substance code and name
-          substance_element = proposal.xpath("./substance/substanceCode").first
-          next unless substance_element
-
-          vaccine_code        = substance_element["code"]
-          vaccine_name        = substance_element["displayName"]
-          vaccine_code_system = substance_element["codeSystem"]
-
-          # Get the clinical observation result
-          observation = proposal.xpath(".//observationResult").first
-          next unless observation
-
-          # Get recommendation status
-          status_element = observation.xpath(".//observationValue/concept").first
-          next unless status_element
-
-          status_code = status_element["code"]
-          status_name = status_element["displayName"]
-
-          # Get interpretation reasons
-          reasons = []
-          observation.xpath(".//interpretation").each do |interpretation|
-            reason = {
-              code: interpretation["code"],
-              name: interpretation["displayName"]
-            }
-
-            # Add supplemental text if available
-            if interpretation["originalText"]
-              reason[:supplemental_text] = interpretation["originalText"]
-            end
-
-            reasons << reason
-          end
-
-          # Get administration time intervals if available
-          proposed_interval = proposal.xpath("./proposedAdministrationTimeInterval").first
-          valid_interval = proposal.xpath("./validAdministrationTimeInterval").first
-
-          intervals = {}
-          if proposed_interval
-            intervals[:proposed] = {
-              low: format_ice_date(proposed_interval["low"]),
-              high: format_ice_date(proposed_interval["high"])
-            }.compact
-          end
-
-          if valid_interval
-            intervals[:valid] = {
-              low: format_ice_date(valid_interval["low"]),
-              high: format_ice_date(valid_interval["high"])
-            }.compact
-          end
-
-          # Build the recommendation object
-          recommendation = {
-            vaccine: {
-              code: vaccine_code,
-              code_system: vaccine_code_system,
-              name: vaccine_name
-            },
-            status: {
-              code: status_code,
-              name: status_name
-            },
-            reasons:
-          }
-
-          # Only add intervals if they exist
-          recommendation[:intervals] = intervals if present?(intervals)
-
-          all_recommendations << recommendation
-        end
-
-        # Create simplified immunization status mapping
-        simplified_status = {}
-
-        # Process all recommendations to create the simplified mapping
-        all_recommendations.each do |recommendation|
-          vaccine_name = recommendation[:vaccine][:name]
-          status_code = recommendation[:status][:code]
-
-          # Map the vaccine name to our key
-          vaccine_key = VACCINE_MAPPING[vaccine_name]
-          next unless vaccine_key # Skip if we don't have a mapping
-
-          # Map the status code to our status
-          status = STATUS_MAPPING[status_code] || "overdue" # Default to overdue if unknown
-
-          # Special handling for conditional status based on reasons
-          if status == "conditional"
-            # Check if any reason indicates medical exemption
-            has_medical_exemption = recommendation[:reasons].any? { |r| r[:code] == "MEDICAL_EXEMPTION" }
-            if has_medical_exemption
-              status = "medically_exempt"
-            end
-          end
-
-          # Store in our simplified mapping
-          simplified_status[vaccine_key] = status
-        end
-
-        # Build the final result structure
-        {
-          raw_xml: xml_string,
-          patient: {
-            id: patient_id,
-            birth_date: birth_date || birth_time,
-            gender:
-          }.compact,
-          recommendations: all_recommendations, # Keep the original flat list for backward compatibility
-          simplified_status: # Add the simplified mapping
-        }
-      end
-
       def handle_error_response(response)
         error_message = "ICE service error: #{response.code}"
 
         begin
           error_details = JSON.parse(response.body)
-          error_message += " - #{error_details['message'] || error_details['error'] || response.body}"
-        rescue
+          error_message += " - #{error_details["message"] || error_details["error"] || response.body}"
+        rescue StandardError
           error_message += " - #{response.body}"
         end
 
         logger.error(error_message)
         { success: false, error: error_message }
       end
-
-      # Helper method to format ICE dates to standard format
-      def format_ice_date(ice_date)
-        return nil unless ice_date
-
-        # ICE dates are in format: YYYYMMDDHHMMSS.000+0000
-        if ice_date.match(/^(\d{4})(\d{2})(\d{2})/)
-          year = $1
-          month = $2
-          day = $3
-          "#{year}-#{month}-#{day}"
-        else
-          ice_date
-        end
-      end
-
-      # Helper method to format dates for ICE (YYYYMMDD)
-      def format_date_for_ice(date_string)
-        return nil unless date_string
-
-        begin
-          date = Date.parse(date_string)
-          # Format as YYYYMMDD
-          date.strftime("%Y%m%d")
-        rescue
-          # If parsing fails, try to use the original string
-          date_string
-        end
-      end
   end
 end

data/lib/hln_ice/evaluations_parser.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module HlnIce
+  # Extracts ICE's evaluation of each administered dose from the vMR patient
+  # element. ICE nests one substanceAdministrationEvent per vaccine group under
+  # each input event, so a combination vaccine yields one evaluation per group
+  # it counts toward.
+  class EvaluationsParser
+    include Support
+
+    def initialize(patient)
+      @patient = patient
+    end
+
+    def evaluations
+      events = patient.xpath("./clinicalStatements/substanceAdministrationEvents/substanceAdministrationEvent")
+
+      events.flat_map do |event|
+        event_id = event.xpath("./id").first&.[]("root")
+        cvx = event.xpath("./substance/substanceCode").first&.[]("code")
+
+        event.xpath("./relatedClinicalStatement/substanceAdministrationEvent").filter_map do |component|
+          parse_evaluation(component, event_id:, cvx:)
+        end
+      end
+    end
+
+    private
+      attr_reader :patient
+
+      # Build the evaluation for one vaccine group from a nested event.
+      # Returns nil when the event has no evaluation status observation.
+      def parse_evaluation(component, event_id:, cvx:)
+        observation = component.xpath("./relatedClinicalStatement/observationResult[observationValue/concept]").first
+        return unless observation
+
+        focus = observation.xpath("./observationFocus").first
+        status = observation.xpath("./observationValue/concept").first
+        dose_number = component.xpath("./doseNumber").first&.[]("value")
+        valid = component.xpath("./isValid").first&.[]("value")
+
+        {
+          event_id:,
+          cvx:,
+          administered_on: format_ice_date(component.xpath("./administrationTimeInterval").first&.[]("low")),
+          vaccine_group: { code: focus&.[]("code"), name: focus&.[]("displayName") },
+          dose_number: dose_number&.to_i,
+          valid: valid.nil? ? nil : valid == "true",
+          status: { code: status["code"], name: status["displayName"] },
+          reasons: observation.xpath("./interpretation").map do |interpretation|
+            { code: interpretation["code"], name: interpretation["displayName"] }
+          end
+        }
+      end
+  end
+end

data/lib/hln_ice/request_builder.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "base64"
+require "securerandom"
+
+module HlnIce
+  # Builds the ICE evaluate request for a patient: the vMR XML, and the JSON
+  # payload that carries it base64 encoded.
+  #
+  # Does no logging; the Client decides what may be logged.
+  class RequestBuilder
+    include Support
+
+    def initialize(patient_data)
+      @patient_data = patient_data
+
+      # Extract patient information
+      @patient_id = patient_data[:patient][:id]
+      @date_of_birth = patient_data[:patient][:date_of_birth]
+      @gender = patient_data[:patient][:gender]
+      @gender = "U" if blank?(@gender) # Set default to 'U' if blank
+    end
+
+    def xml
+      @xml ||= build_xml
+    end
+
+    def payload
+      # Base64 encode the XML
+      base64_encoded_payload = Base64.strict_encode64(xml)
+
+      # Build the full payload
+      {
+        "interactionId" => {
+          "scopingEntityId" => "org.nyc.cir",
+          "interactionId" => "#{patient_id}-#{Time.now.to_i}",
+          "submissionTime" => (Time.now.to_f * 1000).to_i
+        },
+        "evaluationRequest" => {
+          "clientLanguage" => "en",
+          "clientTimeZoneOffset" => "+0000",
+          "kmEvaluationRequest" => [
+            {
+              "kmId" => {
+                "scopingEntityId" => "org.nyc.cir",
+                "businessId" => "ICE",
+                "version" => "1.0.0"
+              }
+            }
+          ],
+          "dataRequirementItemData" => [
+            {
+              "driId" => {
+                "containingEntityId" => {
+                  "scopingEntityId" => "org.nyc.cir",
+                  "businessId" => "ICEData",
+                  "version" => "1.0.0"
+                },
+                "itemId" => "cdsPayload"
+              },
+              "data" => {
+                "informationModelSSId" => {
+                  "scopingEntityId" => "org.opencds.vmr",
+                  "businessId" => "VMR",
+                  "version" => "1.0"
+                },
+                "base64EncodedPayload" => [base64_encoded_payload]
+              }
+            }
+          ]
+        }
+      }
+    end
+
+    private
+      attr_reader :patient_data, :patient_id, :date_of_birth, :gender
+
+      def build_xml
+        # Build the VMR XML
+        xml_payload = <<~XML
+          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+          <ns4:cdsInput xmlns:ns2="org.opencds"
+                        xmlns:ns3="org.opencds.vmr.v1_0.schema.vmr"
+                        xmlns:ns4="org.opencds.vmr.v1_0.schema.cdsinput"
+                        xmlns:ns5="org.opencds.vmr.v1_0.schema.cdsoutput">
+            <templateId root="2.16.840.1.113883.3.795.11.1.1"/>
+            <cdsContext>
+              <cdsSystemUserPreferredLanguage code="en" codeSystem="2.16.840.1.113883.6.99" displayName="English"/>
+            </cdsContext>
+            <vmrInput>
+              <templateId root="2.16.840.1.113883.3.795.11.1.1"/>
+              <patient>
+                <templateId root="2.16.840.1.113883.3.795.11.2.1.1"/>
+                <id root="2.16.840.1.113883.3.795.12.100.11" extension="#{patient_id}"/>
+                <demographics>
+                  <birthTime value="#{format_date_for_ice(date_of_birth)}"/>
+                  <gender code="#{gender}" codeSystem="2.16.840.1.113883.5.1"/>
+                </demographics>
+                <clinicalStatements>
+                  <substanceAdministrationEvents>
+        XML
+
+        # Add immunization records if available
+        if present?(patient_data[:immunizations])
+          patient_data[:immunizations].each do |imm|
+            next unless present?(imm.dig(:clinicalStatements, :substanceAdministrationEvents))
+
+            imm[:clinicalStatements][:substanceAdministrationEvents].each do |event|
+              next unless present?(event.dig(:substance, :substanceCode))
+
+              substance_code = event[:substance][:substanceCode]
+
+              # Format dates to ICE format (YYYYMMDD)
+              low_date = format_date_for_ice(event[:administrationTimeInterval][:low])
+              high_date = format_date_for_ice(event[:administrationTimeInterval][:high])
+
+              xml_payload += <<~XML
+                <substanceAdministrationEvent>
+                  <templateId root="2.16.840.1.113883.3.795.11.9.1.1"/>
+                  <id root="#{event[:id] || SecureRandom.uuid}"/>
+                  <substanceAdministrationGeneralPurpose code="384810002" codeSystem="2.16.840.1.113883.6.5"/>
+                  <substance>
+                    <id root="#{event[:substance][:id] || SecureRandom.uuid}"/>
+                    <substanceCode code="#{substance_code[:code]}"
+                                codeSystem="2.16.840.1.113883.12.292"
+                                displayName="#{substance_code[:displayName]}"
+                                originalText="#{substance_code[:displayName]}"/>
+                  </substance>
+                  <administrationTimeInterval low="#{low_date}" high="#{high_date}"/>
+                </substanceAdministrationEvent>
+              XML
+            end
+          end
+        end
+
+        # Close the XML
+        xml_payload + <<~XML
+                  </substanceAdministrationEvents>
+                </clinicalStatements>
+              </patient>
+            </vmrInput>
+          </ns4:cdsInput>
+        XML
+      end
+  end
+end

data/lib/hln_ice/response_parser.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "nokogiri"
+
+module HlnIce
+  # Parses the body of an ICE evaluate response into the result data:
+  # patient, recommendations, evaluations, and simplified status.
+  #
+  # Does no logging; the Client decides what may be logged.
+  class ResponseParser
+    include Support
+
+    def initialize(response_body)
+      @response_body = response_body
+    end
+
+    # Returns nil when the response carries no vMR payload. Raises if the
+    # body cannot be parsed.
+    def data
+      result = JSON.parse(response_body)
+
+      base64_result = result.dig("finalKMEvaluationResponse", 0, "kmEvaluationResultData", 0, "data",
+                                 "base64EncodedPayload", 0)
+      return unless base64_result
+
+      # Parse the XML response
+      parse_xml_response(Base64.decode64(base64_result))
+    end
+
+    private
+      attr_reader :response_body
+
+      def parse_xml_response(xml_string)
+        # Parse the XML
+        doc = Nokogiri::XML(xml_string)
+
+        # Remove namespaces to simplify parsing
+        doc.remove_namespaces!
+
+        # Extract patient information
+        patient = doc.xpath("//patient").first
+        return { raw_xml: xml_string } unless patient
+
+        patient_id = patient.xpath("./id").first&.[]("extension")
+        birth_time = patient.xpath("./demographics/birthTime").first&.[]("value")
+        gender = patient.xpath("./demographics/gender").first&.[]("code")
+
+        # Format birth date if present
+        birth_date = format_ice_date(birth_time)
+
+        # Extract vaccine recommendations
+        all_recommendations = []
+
+        doc.xpath("//substanceAdministrationProposal").each do |proposal|
+          # Get the substance code and name
+          substance_element = proposal.xpath("./substance/substanceCode").first
+          next unless substance_element
+
+          vaccine_code        = substance_element["code"]
+          vaccine_name        = substance_element["displayName"]
+          vaccine_code_system = substance_element["codeSystem"]
+
+          # Get the clinical observation result carrying the recommendation status.
+          # A proposal may contain other observation results (e.g. schedule
+          # authorities), in any order, so select the one with a status concept.
+          observation = proposal.xpath(".//observationResult[observationValue/concept]").first
+          next unless observation
+
+          # Get recommendation status
+          status_element = observation.xpath(".//observationValue/concept").first
+
+          status_code = status_element["code"]
+          status_name = status_element["displayName"]
+
+          # Get interpretation reasons
+          reasons = []
+          observation.xpath(".//interpretation").each do |interpretation|
+            reason = {
+              code: interpretation["code"],
+              name: interpretation["displayName"]
+            }
+
+            # Add supplemental text if available
+            reason[:supplemental_text] = interpretation["originalText"] if interpretation["originalText"]
+
+            reasons << reason
+          end
+
+          # Get administration time intervals if available
+          proposed_interval = proposal.xpath("./proposedAdministrationTimeInterval").first
+          valid_interval = proposal.xpath("./validAdministrationTimeInterval").first
+
+          intervals = {}
+          if proposed_interval
+            intervals[:proposed] = {
+              low: format_ice_date(proposed_interval["low"]),
+              high: format_ice_date(proposed_interval["high"])
+            }.compact
+          end
+
+          if valid_interval
+            intervals[:valid] = {
+              low: format_ice_date(valid_interval["low"]),
+              high: format_ice_date(valid_interval["high"])
+            }.compact
+          end
+
+          # Build the recommendation object
+          recommendation = {
+            vaccine: {
+              code: vaccine_code,
+              code_system: vaccine_code_system,
+              name: vaccine_name
+            },
+            status: {
+              code: status_code,
+              name: status_name
+            },
+            reasons:
+          }
+
+          # Only add intervals if they exist
+          recommendation[:intervals] = intervals if present?(intervals)
+
+          # Only add schedule authorities if the service returned them
+          # (requires the ICE outputScheduleAuthorities property)
+          schedule_authorities = parse_schedule_authorities(proposal)
+          recommendation[:schedule_authorities] = schedule_authorities if present?(schedule_authorities)
+
+          all_recommendations << recommendation
+        end
+
+        # Build the final result structure
+        {
+          raw_xml: xml_string,
+          patient: {
+            id: patient_id,
+            birth_date: birth_date || birth_time,
+            gender:
+          }.compact,
+          recommendations: all_recommendations, # Keep the original flat list for backward compatibility
+          evaluations: EvaluationsParser.new(patient).evaluations,
+          simplified_status: SimplifiedStatus.new(all_recommendations).to_h
+        }
+      end
+
+      # Extract the schedule authorities (e.g. ACIP_CDC, AAP) for a proposal.
+      # Returns an empty array when the service did not include them.
+      def parse_schedule_authorities(proposal)
+        authorities = proposal.xpath(
+          ".//observationResult[observationFocus/@code='ICE_VACCINE_GROUP_SCHEDULE_AUTHORITIES']/interpretation"
+        )
+
+        authorities.map do |interpretation|
+          {
+            code: interpretation["code"],
+            name: interpretation["displayName"]
+          }
+        end
+      end
+  end
+end

data/lib/hln_ice/simplified_status.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module HlnIce
+  # Maps parsed recommendations to a simplified status keyed by our
+  # immunization keys, e.g. { ipv_opv: "overdue", mmr: "compliant" }.
+  class SimplifiedStatus
+    # Mapping from ICE status codes to our status keys
+    STATUS_MAPPING = {
+      "CONDITIONAL" => "conditional",
+      "FUTURE_RECOMMENDED" => "compliant",
+      "NOT_RECOMMENDED" => "compliant",
+      "RECOMMENDED" => "overdue"
+    }.freeze
+
+    # Mapping from ICE vaccine groups to our immunization keys
+    VACCINE_MAPPING = {
+      "DTP Vaccine Group" => :dtap_tdap,
+      "Hep A Vaccine Group" => :hep_a,
+      "Hep B Vaccine Group" => :hep_b,
+      "Hib Vaccine Group" => :hib,
+      "HPV Vaccine Group" => :hpv,
+      "Meningococcal Vaccine Group" => :mcv4,
+      "MMR Vaccine Group" => :mmr,
+      "Pneumococcal Vaccine Group" => :pcv,
+      "Polio Vaccine Group" => :ipv_opv,
+      "Varicella Vaccine Group" => :var
+    }.freeze
+
+    def initialize(recommendations)
+      @recommendations = recommendations
+    end
+
+    def to_h
+      # Create simplified immunization status mapping
+      simplified_status = {}
+
+      # Process all recommendations to create the simplified mapping
+      recommendations.each do |recommendation|
+        vaccine_name = recommendation[:vaccine][:name]
+        status_code = recommendation[:status][:code]
+
+        # Map the vaccine name to our key
+        vaccine_key = VACCINE_MAPPING[vaccine_name]
+        next unless vaccine_key # Skip if we don't have a mapping
+
+        # Map the status code to our status
+        status = STATUS_MAPPING[status_code] || "overdue" # Default to overdue if unknown
+
+        # Special handling for conditional status based on reasons
+        if status == "conditional"
+          # Check if any reason indicates medical exemption
+          has_medical_exemption = recommendation[:reasons].any? { |r| r[:code] == "MEDICAL_EXEMPTION" }
+          status = "medically_exempt" if has_medical_exemption
+        end
+
+        # Store in our simplified mapping
+        simplified_status[vaccine_key] = status
+      end
+
+      simplified_status
+    end
+
+    private
+      attr_reader :recommendations
+  end
+end

data/lib/hln_ice/support.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "date"
+
+module HlnIce
+  # Helpers shared by the request builder and response parsers. Included as
+  # private instance methods.
+  module Support
+    private
+      # Plain-Ruby equivalent of ActiveSupport's `blank?`.
+      def blank?(value)
+        return true if value.nil?
+        return value.strip.empty? if value.is_a?(String)
+        return value.empty? if value.respond_to?(:empty?)
+
+        false
+      end
+
+      # Plain-Ruby equivalent of ActiveSupport's `present?`.
+      def present?(value)
+        !blank?(value)
+      end
+
+      # Helper method to format ICE dates to standard format
+      def format_ice_date(ice_date)
+        return nil unless ice_date
+
+        # ICE dates are in format: YYYYMMDDHHMMSS.000+0000
+        if ice_date.match(/^(\d{4})(\d{2})(\d{2})/)
+          year = ::Regexp.last_match(1)
+          month = ::Regexp.last_match(2)
+          day = ::Regexp.last_match(3)
+          "#{year}-#{month}-#{day}"
+        else
+          ice_date
+        end
+      end
+
+      # Helper method to format dates for ICE (YYYYMMDD)
+      def format_date_for_ice(date_string)
+        return nil unless date_string
+
+        begin
+          date = Date.parse(date_string)
+          # Format as YYYYMMDD
+          date.strftime("%Y%m%d")
+        rescue StandardError
+          # If parsing fails, try to use the original string
+          date_string
+        end
+      end
+  end
+end

data/lib/hln_ice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HlnIce
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/hln_ice.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "hln_ice/version"
+require_relative "hln_ice/support"
+require_relative "hln_ice/request_builder"
+require_relative "hln_ice/evaluations_parser"
+require_relative "hln_ice/simplified_status"
+require_relative "hln_ice/response_parser"
 require_relative "hln_ice/client"
 
 module HlnIce

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hln_ice
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sam Sohn
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -61,13 +61,18 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- hln_ice.gemspec
 - lib/hln_ice.rb
 - lib/hln_ice/client.rb
+- lib/hln_ice/evaluations_parser.rb
+- lib/hln_ice/request_builder.rb
+- lib/hln_ice/response_parser.rb
+- lib/hln_ice/simplified_status.rb
+- lib/hln_ice/support.rb
 - lib/hln_ice/version.rb
 - sig/hln_ice.rbs
 homepage: https://github.com/PrimaryDotHealth/hln_ice
@@ -78,6 +83,7 @@ metadata:
   homepage_uri: https://github.com/PrimaryDotHealth/hln_ice
   source_code_uri: https://github.com/PrimaryDotHealth/hln_ice
   changelog_uri: https://github.com/PrimaryDotHealth/hln_ice/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -92,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Ruby client for the HLN ICE (Immunization Calculation Engine) OpenCDS service.
 test_files: []

data/hln_ice.gemspec

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/hln_ice/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "hln_ice"
-  spec.version = HlnIce::VERSION
-  spec.authors = ["Sam Sohn"]
-  spec.email = ["sam@primary.health"]
-
-  spec.summary = "Ruby client for the HLN ICE (Immunization Calculation Engine) OpenCDS service."
-  spec.description = "Evaluates a patient's immunization history against the HLN ICE forecasting " \
-                     "rules and returns both the raw recommendations and a simplified status mapping."
-  spec.homepage = "https://github.com/PrimaryDotHealth/hln_ice"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.1.0"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "base64", "~> 0.2"
-  spec.add_dependency "httparty", "~> 0.21"
-  spec.add_dependency "nokogiri", "~> 1.15"
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end