hln_ice 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 5cc821a0690dfaa750fb0dd36f1409a8a20054486318166f708bd8a266ff5c7a
4
+ data.tar.gz: 424486397d7ae838ee6af769155deef6a8b5bff76309291470a295c10eb58389
5
+ SHA512:
6
+ metadata.gz: 172c72400334ad1e9ca73b37fd7c77c7227386336e44e5d751c69d1bf40e021664ac0ceeeb835361924d6ddaff6cc0898420e07f5088fe72925821fdfa35bf11
7
+ data.tar.gz: 1ee834f1abd93c7cb9dc19453a7afd111a39f5745ad12d3d6345bae406805c9fb837fa3aacb80ecc03e9fe81c1cfe6d36d36b6790be2ed657aa0596e147f624d
data/.rspec ADDED
@@ -0,0 +1,3 @@
1
+ --format documentation
2
+ --color
3
+ --require spec_helper
data/.rubocop.yml ADDED
@@ -0,0 +1,13 @@
1
+ AllCops:
2
+ TargetRubyVersion: 3.1
3
+
4
+ Style/StringLiterals:
5
+ Enabled: true
6
+ EnforcedStyle: double_quotes
7
+
8
+ Style/StringLiteralsInInterpolation:
9
+ Enabled: true
10
+ EnforcedStyle: double_quotes
11
+
12
+ Layout/LineLength:
13
+ Max: 120
data/CHANGELOG.md ADDED
@@ -0,0 +1,5 @@
1
+ ## [Unreleased]
2
+
3
+ ## [0.1.0] - 2026-06-22
4
+
5
+ - Initial release
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 Sam Sohn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,156 @@
1
+ # HlnIce
2
+
3
+ A Ruby client for the [HLN ICE](https://www.hln.com/ice/) (Immunization Calculation Engine), an OpenCDS clinical decision-support service for immunization forecasting.
4
+
5
+ Given a patient's demographics and immunization history, `HlnIce` builds the
6
+ VMR (Virtual Medical Record) request, calls the ICE evaluation endpoint, and
7
+ parses the response into:
8
+
9
+ - a full list of **recommendations** (one per vaccine group, with status, reasons, and administration intervals), and
10
+ - a **simplified status** map keyed by vaccine group — e.g. `{ ipv_opv: "overdue", mmr: "compliant" }`.
11
+
12
+ The gem has no Rails or ActiveSupport dependency; it takes an injected logger
13
+ so it can run in any Ruby application.
14
+
15
+ ## Installation
16
+
17
+ Add the gem to your application's `Gemfile`:
18
+
19
+ ```ruby
20
+ gem "hln_ice"
21
+ ```
22
+
23
+ Then run:
24
+
25
+ ```sh
26
+ bundle install
27
+ ```
28
+
29
+ Or install it directly:
30
+
31
+ ```sh
32
+ gem install hln_ice
33
+ ```
34
+
35
+ ## Usage
36
+
37
+ ### Creating a client
38
+
39
+ ```ruby
40
+ client = HlnIce::Client.new(base_url: "https://ice.example.com")
41
+ ```
42
+
43
+ All options:
44
+
45
+ | Option | Default | Description |
46
+ | ------------- | ------------------------ | ----------------------------------------------------- |
47
+ | `base_url:` | _(required)_ | Base URL of the ICE OpenCDS service. |
48
+ | `timeout:` | `30` | HTTP request timeout, in seconds. |
49
+ | `max_retries:`| `3` | Number of retries on a failed evaluation request. |
50
+ | `retry_delay:`| `1` | Seconds to wait between retries. |
51
+ | `logger:` | `Logger.new($stdout)` | Any `Logger`-compatible object. In Rails, pass `Rails.logger`. |
52
+
53
+ ```ruby
54
+ # In a Rails app, reuse the application logger:
55
+ client = HlnIce::Client.new(base_url: ENV["ICE_URL"], logger: Rails.logger)
56
+ ```
57
+
58
+ ### Checking availability
59
+
60
+ ```ruby
61
+ client.available? # => true / false
62
+ ```
63
+
64
+ ### Evaluating immunizations
65
+
66
+ Pass a patient hash with their demographics and (optionally) prior
67
+ immunization events:
68
+
69
+ ```ruby
70
+ patient_data = {
71
+ patient: {
72
+ id: "12345",
73
+ date_of_birth: "2020-01-01", # parseable date string
74
+ gender: "M" # "M", "F", or blank (defaults to "U")
75
+ },
76
+ immunizations: [
77
+ {
78
+ clinicalStatements: {
79
+ substanceAdministrationEvents: [
80
+ {
81
+ substance: {
82
+ substanceCode: { code: "10", displayName: "Polio" }
83
+ },
84
+ administrationTimeInterval: { low: "2020-03-01", high: "2020-03-01" }
85
+ }
86
+ ]
87
+ }
88
+ }
89
+ ]
90
+ }
91
+
92
+ result = client.evaluate_immunizations(patient_data)
93
+ ```
94
+
95
+ ### The result
96
+
97
+ On success:
98
+
99
+ ```ruby
100
+ {
101
+ success: true,
102
+ data: {
103
+ raw_xml: "<...the decoded ICE response XML...>",
104
+ patient: { id: "12345", birth_date: "2020-01-01", gender: "M" },
105
+ recommendations: [
106
+ {
107
+ vaccine: { code: "10", code_system: "...", name: "Polio Vaccine Group" },
108
+ status: { code: "RECOMMENDED", name: "Recommended" },
109
+ reasons: [{ code: "DUE_NOW", name: "Due Now" }],
110
+ intervals: { proposed: { low: "2020-03-01", high: "2020-04-01" } }
111
+ }
112
+ ],
113
+ simplified_status: { ipv_opv: "overdue" }
114
+ }
115
+ }
116
+ ```
117
+
118
+ On failure (service error, timeout after retries, or unparseable response):
119
+
120
+ ```ruby
121
+ { success: false, error: "ICE service error: 400 - ..." }
122
+ ```
123
+
124
+ Always branch on `result[:success]` before reading `result[:data]`.
125
+
126
+ ### Simplified status values
127
+
128
+ `simplified_status` maps each recognized vaccine group to one of:
129
+
130
+ | Value | Meaning |
131
+ | ------------------ | ----------------------------------------------------------- |
132
+ | `"compliant"` | Up to date (ICE `FUTURE_RECOMMENDED` / `NOT_RECOMMENDED`). |
133
+ | `"overdue"` | A dose is recommended now (ICE `RECOMMENDED`). |
134
+ | `"conditional"` | Conditionally recommended (ICE `CONDITIONAL`). |
135
+ | `"medically_exempt"` | Conditional status with a medical-exemption reason. |
136
+
137
+ The recognized vaccine-group keys are: `:dtap_tdap`, `:hep_a`, `:hep_b`,
138
+ `:hib`, `:hpv`, `:mcv4`, `:mmr`, `:pcv`, `:ipv_opv`, and `:var`.
139
+
140
+ ## Development
141
+
142
+ After checking out the repo, run `bin/setup` to install dependencies. Then,
143
+ run `rake spec` to run the tests. You can also run `bin/console` for an
144
+ interactive prompt that will allow you to experiment.
145
+
146
+ To install this gem onto your local machine, run `bundle exec rake install`.
147
+
148
+ ## Contributing
149
+
150
+ Bug reports and pull requests are welcome on GitHub at
151
+ https://github.com/PrimaryDotHealth/hln_ice.
152
+
153
+ ## License
154
+
155
+ The gem is available as open source under the terms of the
156
+ [MIT License](https://opensource.org/licenses/MIT).
data/Rakefile ADDED
@@ -0,0 +1,12 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "bundler/gem_tasks"
4
+ require "rspec/core/rake_task"
5
+
6
+ RSpec::Core::RakeTask.new(:spec)
7
+
8
+ require "rubocop/rake_task"
9
+
10
+ RuboCop::RakeTask.new
11
+
12
+ task default: %i[spec rubocop]
@@ -0,0 +1,455 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "date"
4
+ require "json"
5
+ require "base64"
6
+ require "logger"
7
+ require "securerandom"
8
+ require "httparty"
9
+ require "nokogiri"
10
+
11
+ module HlnIce
12
+ # Client for the HLN ICE (Immunization Calculation Engine) OpenCDS service.
13
+ #
14
+ # Evaluates a patient's immunization history against the ICE forecasting
15
+ # rules and returns both the raw recommendations and a simplified status
16
+ # mapping keyed by vaccine group.
17
+ class Client
18
+ # Mapping from ICE status codes to our status keys
19
+ STATUS_MAPPING = {
20
+ "CONDITIONAL" => "conditional",
21
+ "FUTURE_RECOMMENDED" => "compliant",
22
+ "NOT_RECOMMENDED" => "compliant",
23
+ "RECOMMENDED" => "overdue",
24
+ }.freeze
25
+
26
+ # Mapping from ICE vaccine groups to our immunization keys
27
+ VACCINE_MAPPING = {
28
+ "DTP Vaccine Group" => :dtap_tdap,
29
+ "Hep A Vaccine Group" => :hep_a,
30
+ "Hep B Vaccine Group" => :hep_b,
31
+ "Hib Vaccine Group" => :hib,
32
+ "HPV Vaccine Group" => :hpv,
33
+ "Meningococcal Vaccine Group" => :mcv4,
34
+ "MMR Vaccine Group" => :mmr,
35
+ "Pneumococcal Vaccine Group" => :pcv,
36
+ "Polio Vaccine Group" => :ipv_opv,
37
+ "Varicella Vaccine Group" => :var,
38
+ }.freeze
39
+
40
+ attr_reader :base_url, :timeout, :max_retries, :retry_delay, :logger
41
+
42
+ def initialize(base_url:, timeout: 30, max_retries: 3, retry_delay: 1, logger: nil)
43
+ @base_url = base_url
44
+ @timeout = timeout
45
+ @max_retries = max_retries
46
+ @retry_delay = retry_delay
47
+ @logger = logger || Logger.new($stdout)
48
+ end
49
+
50
+ # Check if the ICE service is available
51
+ def available?
52
+ url = "#{base_url}/opencds-decision-support-service/version"
53
+
54
+ begin
55
+ response = HTTParty.get(
56
+ url,
57
+ timeout:
58
+ )
59
+
60
+ response.success?
61
+ rescue => e
62
+ logger.error("ICE service unavailable: #{e.message}")
63
+ false
64
+ end
65
+ end
66
+
67
+ # Evaluate immunizations using patient data
68
+ def evaluate_immunizations(patient_data)
69
+ url = "#{base_url}/opencds-decision-support-service/api/resources/evaluate"
70
+
71
+ # Build the payload for the ICE service
72
+ payload = build_ice_payload(patient_data)
73
+
74
+ # Make the request with retries
75
+ response = nil
76
+ retries = 0
77
+
78
+ begin
79
+ response = HTTParty.post(
80
+ url,
81
+ body: payload.to_json,
82
+ headers: {
83
+ "Content-Type": "application/json",
84
+ "Accept": "application/json"
85
+ },
86
+ timeout:
87
+ )
88
+
89
+ if response.success?
90
+ parse_ice_response(response.body)
91
+ else
92
+ handle_error_response(response)
93
+ end
94
+ rescue => e
95
+ retries += 1
96
+ if retries <= max_retries
97
+ logger.warn("Retrying ICE request (#{retries}/#{max_retries}): #{e.message}")
98
+ sleep(retry_delay)
99
+ retry
100
+ else
101
+ logger.error("Error evaluating immunizations after #{max_retries} retries: #{e.message}")
102
+ { success: false, error: "Error evaluating immunizations: #{e.message}" }
103
+ end
104
+ end
105
+ end
106
+
107
+ private
108
+ # Plain-Ruby equivalent of ActiveSupport's `blank?`.
109
+ def blank?(value)
110
+ return true if value.nil?
111
+ return value.strip.empty? if value.is_a?(String)
112
+ return value.empty? if value.respond_to?(:empty?)
113
+
114
+ false
115
+ end
116
+
117
+ # Plain-Ruby equivalent of ActiveSupport's `present?`.
118
+ def present?(value)
119
+ !blank?(value)
120
+ end
121
+
122
+ def build_ice_payload(patient_data)
123
+ # Extract patient information
124
+ patient_id = patient_data[:patient][:id]
125
+ date_of_birth = patient_data[:patient][:date_of_birth]
126
+ gender = patient_data[:patient][:gender]
127
+ gender = "U" if blank?(gender) # Set default to 'U' if blank
128
+
129
+ # Log input data for debugging
130
+ logger.debug("ICE Input Data: #{JSON.pretty_generate(patient_data)}")
131
+
132
+ # Build the VMR XML
133
+ xml_payload = <<~XML
134
+ <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
135
+ <ns4:cdsInput xmlns:ns2="org.opencds"
136
+ xmlns:ns3="org.opencds.vmr.v1_0.schema.vmr"
137
+ xmlns:ns4="org.opencds.vmr.v1_0.schema.cdsinput"
138
+ xmlns:ns5="org.opencds.vmr.v1_0.schema.cdsoutput">
139
+ <templateId root="2.16.840.1.113883.3.795.11.1.1"/>
140
+ <cdsContext>
141
+ <cdsSystemUserPreferredLanguage code="en" codeSystem="2.16.840.1.113883.6.99" displayName="English"/>
142
+ </cdsContext>
143
+ <vmrInput>
144
+ <templateId root="2.16.840.1.113883.3.795.11.1.1"/>
145
+ <patient>
146
+ <templateId root="2.16.840.1.113883.3.795.11.2.1.1"/>
147
+ <id root="2.16.840.1.113883.3.795.12.100.11" extension="#{patient_id}"/>
148
+ <demographics>
149
+ <birthTime value="#{format_date_for_ice(date_of_birth)}"/>
150
+ <gender code="#{gender}" codeSystem="2.16.840.1.113883.5.1"/>
151
+ </demographics>
152
+ <clinicalStatements>
153
+ <substanceAdministrationEvents>
154
+ XML
155
+
156
+ # Add immunization records if available
157
+ if present?(patient_data[:immunizations])
158
+ patient_data[:immunizations].each do |imm|
159
+ next unless present?(imm.dig(:clinicalStatements, :substanceAdministrationEvents))
160
+
161
+ imm[:clinicalStatements][:substanceAdministrationEvents].each do |event|
162
+ next unless present?(event.dig(:substance, :substanceCode))
163
+
164
+ substance_code = event[:substance][:substanceCode]
165
+
166
+ # Format dates to ICE format (YYYYMMDD)
167
+ low_date = format_date_for_ice(event[:administrationTimeInterval][:low])
168
+ high_date = format_date_for_ice(event[:administrationTimeInterval][:high])
169
+
170
+ xml_payload += <<~XML
171
+ <substanceAdministrationEvent>
172
+ <templateId root="2.16.840.1.113883.3.795.11.9.1.1"/>
173
+ <id root="#{event[:id] || SecureRandom.uuid}"/>
174
+ <substanceAdministrationGeneralPurpose code="384810002" codeSystem="2.16.840.1.113883.6.5"/>
175
+ <substance>
176
+ <id root="#{event[:substance][:id] || SecureRandom.uuid}"/>
177
+ <substanceCode code="#{substance_code[:code]}"
178
+ codeSystem="2.16.840.1.113883.12.292"
179
+ displayName="#{substance_code[:displayName]}"
180
+ originalText="#{substance_code[:displayName]}"/>
181
+ </substance>
182
+ <administrationTimeInterval low="#{low_date}" high="#{high_date}"/>
183
+ </substanceAdministrationEvent>
184
+ XML
185
+ end
186
+ end
187
+ end
188
+
189
+ # Close the XML
190
+ xml_payload += <<~XML
191
+ </substanceAdministrationEvents>
192
+ </clinicalStatements>
193
+ </patient>
194
+ </vmrInput>
195
+ </ns4:cdsInput>
196
+ XML
197
+
198
+ # Log the generated XML for debugging
199
+ logger.debug("Generated ICE XML: #{xml_payload}")
200
+
201
+ # Base64 encode the XML
202
+ base64_encoded_payload = Base64.strict_encode64(xml_payload)
203
+
204
+ # Build the full payload
205
+ {
206
+ "interactionId" => {
207
+ "scopingEntityId" => "org.nyc.cir",
208
+ "interactionId" => "#{patient_id}-#{Time.now.to_i}",
209
+ "submissionTime" => (Time.now.to_f * 1000).to_i
210
+ },
211
+ "evaluationRequest" => {
212
+ "clientLanguage" => "en",
213
+ "clientTimeZoneOffset" => "+0000",
214
+ "kmEvaluationRequest" => [
215
+ {
216
+ "kmId" => {
217
+ "scopingEntityId" => "org.nyc.cir",
218
+ "businessId" => "ICE",
219
+ "version" => "1.0.0"
220
+ }
221
+ }
222
+ ],
223
+ "dataRequirementItemData" => [
224
+ {
225
+ "driId" => {
226
+ "containingEntityId" => {
227
+ "scopingEntityId" => "org.nyc.cir",
228
+ "businessId" => "ICEData",
229
+ "version" => "1.0.0"
230
+ },
231
+ "itemId" => "cdsPayload"
232
+ },
233
+ "data" => {
234
+ "informationModelSSId" => {
235
+ "scopingEntityId" => "org.opencds.vmr",
236
+ "businessId" => "VMR",
237
+ "version" => "1.0"
238
+ },
239
+ "base64EncodedPayload" => [base64_encoded_payload]
240
+ }
241
+ }
242
+ ]
243
+ }
244
+ }
245
+ end
246
+
247
+ def parse_ice_response(response_body)
248
+ logger.info("ICE service response: #{response_body}")
249
+
250
+ result = JSON.parse(response_body)
251
+
252
+ if result.dig("finalKMEvaluationResponse", 0, "kmEvaluationResultData", 0, "data", "base64EncodedPayload", 0)
253
+ base64_result = result["finalKMEvaluationResponse"][0]["kmEvaluationResultData"][0]["data"]["base64EncodedPayload"][0]
254
+ decoded_result = Base64.decode64(base64_result)
255
+
256
+ # Parse the XML response
257
+ parsed_result = parse_xml_response(decoded_result)
258
+
259
+ {
260
+ success: true,
261
+ data: parsed_result
262
+ }
263
+ else
264
+ logger.warn("No valid response found in ICE output.")
265
+ {
266
+ success: false,
267
+ error: "No valid response found in ICE output."
268
+ }
269
+ end
270
+ rescue => e
271
+ logger.error("Error parsing ICE response: #{e.message}")
272
+ { success: false, error: "Error parsing ICE response: #{e.message}" }
273
+ end
274
+
275
+ def parse_xml_response(xml_string)
276
+ # Parse the XML
277
+ doc = Nokogiri::XML(xml_string)
278
+
279
+ # Remove namespaces to simplify parsing
280
+ doc.remove_namespaces!
281
+
282
+ # Extract patient information
283
+ patient = doc.xpath("//patient").first
284
+ return { raw_xml: xml_string } unless patient
285
+
286
+ patient_id = patient.xpath("./id").first["extension"] rescue nil
287
+ birth_time = patient.xpath("./demographics/birthTime").first["value"] rescue nil
288
+ gender = patient.xpath("./demographics/gender").first["code"] rescue nil
289
+
290
+ # Format birth date if present
291
+ birth_date = format_ice_date(birth_time)
292
+
293
+ # Extract vaccine recommendations
294
+ all_recommendations = []
295
+
296
+ doc.xpath("//substanceAdministrationProposal").each do |proposal|
297
+ # Get the substance code and name
298
+ substance_element = proposal.xpath("./substance/substanceCode").first
299
+ next unless substance_element
300
+
301
+ vaccine_code = substance_element["code"]
302
+ vaccine_name = substance_element["displayName"]
303
+ vaccine_code_system = substance_element["codeSystem"]
304
+
305
+ # Get the clinical observation result
306
+ observation = proposal.xpath(".//observationResult").first
307
+ next unless observation
308
+
309
+ # Get recommendation status
310
+ status_element = observation.xpath(".//observationValue/concept").first
311
+ next unless status_element
312
+
313
+ status_code = status_element["code"]
314
+ status_name = status_element["displayName"]
315
+
316
+ # Get interpretation reasons
317
+ reasons = []
318
+ observation.xpath(".//interpretation").each do |interpretation|
319
+ reason = {
320
+ code: interpretation["code"],
321
+ name: interpretation["displayName"]
322
+ }
323
+
324
+ # Add supplemental text if available
325
+ if interpretation["originalText"]
326
+ reason[:supplemental_text] = interpretation["originalText"]
327
+ end
328
+
329
+ reasons << reason
330
+ end
331
+
332
+ # Get administration time intervals if available
333
+ proposed_interval = proposal.xpath("./proposedAdministrationTimeInterval").first
334
+ valid_interval = proposal.xpath("./validAdministrationTimeInterval").first
335
+
336
+ intervals = {}
337
+ if proposed_interval
338
+ intervals[:proposed] = {
339
+ low: format_ice_date(proposed_interval["low"]),
340
+ high: format_ice_date(proposed_interval["high"])
341
+ }.compact
342
+ end
343
+
344
+ if valid_interval
345
+ intervals[:valid] = {
346
+ low: format_ice_date(valid_interval["low"]),
347
+ high: format_ice_date(valid_interval["high"])
348
+ }.compact
349
+ end
350
+
351
+ # Build the recommendation object
352
+ recommendation = {
353
+ vaccine: {
354
+ code: vaccine_code,
355
+ code_system: vaccine_code_system,
356
+ name: vaccine_name
357
+ },
358
+ status: {
359
+ code: status_code,
360
+ name: status_name
361
+ },
362
+ reasons:
363
+ }
364
+
365
+ # Only add intervals if they exist
366
+ recommendation[:intervals] = intervals if present?(intervals)
367
+
368
+ all_recommendations << recommendation
369
+ end
370
+
371
+ # Create simplified immunization status mapping
372
+ simplified_status = {}
373
+
374
+ # Process all recommendations to create the simplified mapping
375
+ all_recommendations.each do |recommendation|
376
+ vaccine_name = recommendation[:vaccine][:name]
377
+ status_code = recommendation[:status][:code]
378
+
379
+ # Map the vaccine name to our key
380
+ vaccine_key = VACCINE_MAPPING[vaccine_name]
381
+ next unless vaccine_key # Skip if we don't have a mapping
382
+
383
+ # Map the status code to our status
384
+ status = STATUS_MAPPING[status_code] || "overdue" # Default to overdue if unknown
385
+
386
+ # Special handling for conditional status based on reasons
387
+ if status == "conditional"
388
+ # Check if any reason indicates medical exemption
389
+ has_medical_exemption = recommendation[:reasons].any? { |r| r[:code] == "MEDICAL_EXEMPTION" }
390
+ if has_medical_exemption
391
+ status = "medically_exempt"
392
+ end
393
+ end
394
+
395
+ # Store in our simplified mapping
396
+ simplified_status[vaccine_key] = status
397
+ end
398
+
399
+ # Build the final result structure
400
+ {
401
+ raw_xml: xml_string,
402
+ patient: {
403
+ id: patient_id,
404
+ birth_date: birth_date || birth_time,
405
+ gender:
406
+ }.compact,
407
+ recommendations: all_recommendations, # Keep the original flat list for backward compatibility
408
+ simplified_status: # Add the simplified mapping
409
+ }
410
+ end
411
+
412
+ def handle_error_response(response)
413
+ error_message = "ICE service error: #{response.code}"
414
+
415
+ begin
416
+ error_details = JSON.parse(response.body)
417
+ error_message += " - #{error_details['message'] || error_details['error'] || response.body}"
418
+ rescue
419
+ error_message += " - #{response.body}"
420
+ end
421
+
422
+ logger.error(error_message)
423
+ { success: false, error: error_message }
424
+ end
425
+
426
+ # Helper method to format ICE dates to standard format
427
+ def format_ice_date(ice_date)
428
+ return nil unless ice_date
429
+
430
+ # ICE dates are in format: YYYYMMDDHHMMSS.000+0000
431
+ if ice_date.match(/^(\d{4})(\d{2})(\d{2})/)
432
+ year = $1
433
+ month = $2
434
+ day = $3
435
+ "#{year}-#{month}-#{day}"
436
+ else
437
+ ice_date
438
+ end
439
+ end
440
+
441
+ # Helper method to format dates for ICE (YYYYMMDD)
442
+ def format_date_for_ice(date_string)
443
+ return nil unless date_string
444
+
445
+ begin
446
+ date = Date.parse(date_string)
447
+ # Format as YYYYMMDD
448
+ date.strftime("%Y%m%d")
449
+ rescue
450
+ # If parsing fails, try to use the original string
451
+ date_string
452
+ end
453
+ end
454
+ end
455
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module HlnIce
4
+ VERSION = "0.1.0"
5
+ end
data/lib/hln_ice.rb ADDED
@@ -0,0 +1,8 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "hln_ice/version"
4
+ require_relative "hln_ice/client"
5
+
6
+ module HlnIce
7
+ class Error < StandardError; end
8
+ end
data/sig/hln_ice.rbs ADDED
@@ -0,0 +1,4 @@
1
+ module HlnIce
2
+ VERSION: String
3
+ # See the writing guide of rbs: https://github.com/ruby/rbs#guides
4
+ end
metadata ADDED
@@ -0,0 +1,100 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: hln_ice
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Sam Sohn
8
+ autorequire:
9
+ bindir: exe
10
+ cert_chain: []
11
+ date: 2026-06-22 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: base64
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - "~>"
18
+ - !ruby/object:Gem::Version
19
+ version: '0.2'
20
+ type: :runtime
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ - - "~>"
25
+ - !ruby/object:Gem::Version
26
+ version: '0.2'
27
+ - !ruby/object:Gem::Dependency
28
+ name: httparty
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - "~>"
32
+ - !ruby/object:Gem::Version
33
+ version: '0.21'
34
+ type: :runtime
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - "~>"
39
+ - !ruby/object:Gem::Version
40
+ version: '0.21'
41
+ - !ruby/object:Gem::Dependency
42
+ name: nokogiri
43
+ requirement: !ruby/object:Gem::Requirement
44
+ requirements:
45
+ - - "~>"
46
+ - !ruby/object:Gem::Version
47
+ version: '1.15'
48
+ type: :runtime
49
+ prerelease: false
50
+ version_requirements: !ruby/object:Gem::Requirement
51
+ requirements:
52
+ - - "~>"
53
+ - !ruby/object:Gem::Version
54
+ version: '1.15'
55
+ description: Evaluates a patient's immunization history against the HLN ICE forecasting
56
+ rules and returns both the raw recommendations and a simplified status mapping.
57
+ email:
58
+ - sam@primary.health
59
+ executables: []
60
+ extensions: []
61
+ extra_rdoc_files: []
62
+ files:
63
+ - ".rspec"
64
+ - ".rubocop.yml"
65
+ - CHANGELOG.md
66
+ - LICENSE.txt
67
+ - README.md
68
+ - Rakefile
69
+ - lib/hln_ice.rb
70
+ - lib/hln_ice/client.rb
71
+ - lib/hln_ice/version.rb
72
+ - sig/hln_ice.rbs
73
+ homepage: https://github.com/PrimaryDotHealth/hln_ice
74
+ licenses:
75
+ - MIT
76
+ metadata:
77
+ allowed_push_host: https://rubygems.org
78
+ homepage_uri: https://github.com/PrimaryDotHealth/hln_ice
79
+ source_code_uri: https://github.com/PrimaryDotHealth/hln_ice
80
+ changelog_uri: https://github.com/PrimaryDotHealth/hln_ice/blob/main/CHANGELOG.md
81
+ post_install_message:
82
+ rdoc_options: []
83
+ require_paths:
84
+ - lib
85
+ required_ruby_version: !ruby/object:Gem::Requirement
86
+ requirements:
87
+ - - ">="
88
+ - !ruby/object:Gem::Version
89
+ version: 3.1.0
90
+ required_rubygems_version: !ruby/object:Gem::Requirement
91
+ requirements:
92
+ - - ">="
93
+ - !ruby/object:Gem::Version
94
+ version: '0'
95
+ requirements: []
96
+ rubygems_version: 3.5.3
97
+ signing_key:
98
+ specification_version: 4
99
+ summary: Ruby client for the HLN ICE (Immunization Calculation Engine) OpenCDS service.
100
+ test_files: []