data_nexus 0.3.0 → 0.5.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 11502860850ccde0aa9b28ec2770d583d716af03d2d8a2cba9beb60383933dae
4
- data.tar.gz: a9e2a9215fb714a6a015d629de69dc112d55697f8d1c227a61689b2f8fbe3c56
3
+ metadata.gz: 6d29740e8f62470f6555a1223aa80f5d4737d09694520088ee72707578928177
4
+ data.tar.gz: c7f44d3575c7e2a9e53fcb62b5be62e56da785d6ee551dd3c5b019142f3b0392
5
5
  SHA512:
6
- metadata.gz: af48c59e9c0f360b3ec058721e80cfc36f7c6067420097c86c60129d7455e92c06601185e5a40df232b2d1b2c08a05137ed2231b470c8defb52c7eddf65246ed
7
- data.tar.gz: e6f73e656deb92723c946d49299019081eedddacb866e608c961107cf92421396f790ca2329a00abd9223b06e5a9c5a364b326cba79a5e4ae8d3cbc530d2a0e2
6
+ metadata.gz: a95ab23b61f761d81266235cdfd870ace57ec5b3412871a22dce341355e6bc593254e55b2a32c5044faf3fe8eb99e289fa24d91ba0205399648833f18c0c7e3e
7
+ data.tar.gz: 7daf503e0dd201b58f01fc80c148e521c7b4767771fcf32e150975204140f9e791e4337a8b58713debbc38bdada98541272efdce51ade41220248eef12efa6cb
@@ -0,0 +1,2 @@
1
+ # Every change needs an approving review from one of these people.
2
+ * @fastjames @k1bs @briansage
@@ -15,7 +15,7 @@ jobs:
15
15
  strategy:
16
16
  fail-fast: false
17
17
  matrix:
18
- ruby-version: ["3.0", "3.1", "3.2", "3.4", "4.0"]
18
+ ruby-version: ["3.3", "3.4", "4.0"]
19
19
 
20
20
  steps:
21
21
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -23,7 +23,7 @@ jobs:
23
23
  persist-credentials: false
24
24
 
25
25
  - name: Set up Ruby ${{ matrix.ruby-version }}
26
- uses: ruby/setup-ruby@e8944e80fb94b20106697132f8c20c665fab29e9 # v1.325.0
26
+ uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
27
27
  with:
28
28
  ruby-version: ${{ matrix.ruby-version }}
29
29
  bundler-cache: true
@@ -40,9 +40,9 @@ jobs:
40
40
  persist-credentials: false
41
41
 
42
42
  - name: Set up Ruby
43
- uses: ruby/setup-ruby@e8944e80fb94b20106697132f8c20c665fab29e9 # v1.325.0
43
+ uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
44
44
  with:
45
- ruby-version: "3.2"
45
+ ruby-version: "3.3"
46
46
  bundler-cache: true
47
47
 
48
48
  - name: Run RuboCop
@@ -44,7 +44,7 @@ jobs:
44
44
  persist-credentials: false
45
45
 
46
46
  - name: Run zizmor
47
- uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482 # v0.6.4
47
+ uses: zizmorcore/zizmor-action@45d7276c9ca790aabd705e31ca99c6185c3e76dd # v0.8.1
48
48
  with:
49
49
  # Annotations, not SARIF. In SARIF mode zizmor exits 0 whatever it
50
50
  # finds, so `advanced-security: true` would quietly turn this gate
@@ -37,9 +37,9 @@ jobs:
37
37
  # cache, so a restored cache could hand the release poisoned
38
38
  # dependencies. A fresh install costs seconds.
39
39
  - name: Set up Ruby
40
- uses: ruby/setup-ruby@e8944e80fb94b20106697132f8c20c665fab29e9 # v1.325.0
40
+ uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
41
41
  with:
42
- ruby-version: "3.2"
42
+ ruby-version: "3.3"
43
43
 
44
44
  - name: Install dependencies
45
45
  run: bundle install
data/.rubocop.yml CHANGED
@@ -3,7 +3,7 @@ plugins:
3
3
  - rubocop-rspec
4
4
 
5
5
  AllCops:
6
- TargetRubyVersion: 3.0
6
+ TargetRubyVersion: 3.3
7
7
  NewCops: enable
8
8
 
9
9
  # Integration tests have different expectations
@@ -26,3 +26,4 @@ RSpec/MultipleMemoizedHelpers:
26
26
  Metrics/ParameterLists:
27
27
  Exclude:
28
28
  - "lib/data_nexus/client.rb"
29
+ - "lib/data_nexus/configuration.rb"
data/AGENTS.md CHANGED
@@ -20,11 +20,17 @@
20
20
 
21
21
  ## Development
22
22
 
23
- - Ruby >= 3.0.0
23
+ - Ruby >= 3.3.0
24
24
  - Run `bundle install` to install dependencies
25
25
  - Run `bundle exec rspec` to run tests
26
26
  - Run `bundle exec rubocop` to lint
27
27
 
28
+ ## Pull requests
29
+
30
+ Every pull request needs an approving review from a code owner listed in `.github/CODEOWNERS` before it can merge. An automated review, such as CodeRabbit's, doesn't count, and a push after the approval needs a fresh one. Never mark a pull request ready to merge on a bot's approval alone; ask a code owner to review it.
31
+
32
+ This repository is public. Never name a Dart Health client in a commit, pull request, issue or doc; write "a client".
33
+
28
34
  ## GitHub Actions scanning
29
35
 
30
36
  `.github/workflows/github-actions-scan.yml` runs zizmor (security) and actionlint (correctness) on every PR and on every push to `main`, and fails on any finding. Before pushing a workflow change, run both locally:
data/CHANGELOG.md CHANGED
@@ -6,6 +6,19 @@ Dependency bumps, CI changes and test-only changes are left out. From 0.2.0 on,
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.5.0] - 2026-11-16
10
+
11
+ ### Added
12
+
13
+ - `client.programs('program-id').verify_member(first_name:, last_name:, born_on:, employee_id:)` checks whether a person is an eligible member of a program. It returns a hash with `:status` (`"verified"`, `"ineligible"`, `"not_found"` or `"multiple_matches"`) and `:member_id`, which is `nil` unless the status is `verified` or `ineligible`. A `nil` or blank field raises `ArgumentError` naming the field, before any request is sent. A 404 raises `DataNexus::NotFoundError` and is never reported as `not_found` ([sc-7485](https://app.shortcut.com/dart/story/7485)).
14
+ - `max_retries:` on `DataNexus::Client.new` and `DataNexus::Configuration.new` sets how many times a timed-out or failed GET, PUT or DELETE is retried. It defaults to 2, the number the gem always used, and `0` turns retries off. POST and PATCH requests are still never retried ([sc-7485](https://app.shortcut.com/dart/story/7485)).
15
+
16
+ ## [0.4.0] - 2026-10-22
17
+
18
+ ### Removed
19
+
20
+ - Support for Ruby 3.0, 3.1 and 3.2, which are past end-of-life. The gem now requires Ruby 3.3 or later ([sc-7095](https://app.shortcut.com/dart/story/7095)).
21
+
9
22
  ## [0.3.0] - 2026-10-02
10
23
 
11
24
  ### Added
@@ -61,7 +74,9 @@ Tagged but not published to RubyGems. 0.2.0 was the first published version and
61
74
  - `DataNexus::Collection` for cursor-paginated lists (`next_page`, `previous_page`, `each_page`, `each`).
62
75
  - Error classes for API errors (`AuthenticationError`, `NotFoundError`, `RateLimitError` and others) and connection errors.
63
76
 
64
- [Unreleased]: https://github.com/DartHealth/datanexus-ruby/compare/v0.3.0...HEAD
77
+ [Unreleased]: https://github.com/DartHealth/datanexus-ruby/compare/v0.5.0...HEAD
78
+ [0.5.0]: https://github.com/DartHealth/datanexus-ruby/compare/v0.4.0...v0.5.0
79
+ [0.4.0]: https://github.com/DartHealth/datanexus-ruby/compare/v0.3.0...v0.4.0
65
80
  [0.3.0]: https://github.com/DartHealth/datanexus-ruby/compare/v0.2.2...v0.3.0
66
81
  [0.2.2]: https://github.com/DartHealth/datanexus-ruby/compare/v0.2.1...v0.2.2
67
82
  [0.2.1]: https://github.com/DartHealth/datanexus-ruby/compare/v0.2.0...v0.2.1
data/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  Ruby client for the DataNexus API.
4
4
 
5
+ The full API reference is in [DartHealth/datanexus-openapi](https://github.com/DartHealth/datanexus-openapi).
6
+
5
7
  ## Installation
6
8
 
7
9
  ```ruby
@@ -11,12 +13,31 @@ gem 'data_nexus'
11
13
  ## Usage
12
14
 
13
15
  ```ruby
16
+ require 'data_nexus'
17
+
14
18
  client = DataNexus::Client.new(
15
19
  api_key: ENV['DATANEXUS_API_KEY'],
16
20
  base_url: 'https://datanexus.darthealth.com' # optional
17
21
  )
18
22
  ```
19
23
 
24
+ ### Timeouts and Retries
25
+
26
+ A request times out after `timeout` seconds (default 30), and a connection attempt after `open_timeout` seconds (default 10). A timed-out or failed GET, PUT or DELETE is retried up to `max_retries` times (default 2), waiting 0.5 seconds before the first retry and doubling the wait for each one after. POST and PATCH requests, such as `search_members` and `verify_member`, are never retried.
27
+
28
+ A member-facing check that must answer quickly can lower the timeouts and turn retries off:
29
+
30
+ ```ruby
31
+ client = DataNexus::Client.new(
32
+ api_key: ENV['DATANEXUS_API_KEY'],
33
+ timeout: 2,
34
+ open_timeout: 1,
35
+ max_retries: 0
36
+ )
37
+ ```
38
+
39
+ `DataNexus::Configuration.new` takes the same `max_retries:` setting.
40
+
20
41
  ## Programs
21
42
 
22
43
  ### List Programs
@@ -112,6 +133,35 @@ Note: `search_members` does not support pagination. It returns up to 10 results
112
133
 
113
134
  Note: Depending on your API key, `search_members` may be the only method you have access to. Contact your DataNexus representative for more information about your API key's permissions.
114
135
 
136
+ ### Verify Member
137
+
138
+ Check whether a person is an eligible member of a program. All four fields are required.
139
+
140
+ ```ruby
141
+ result = client.programs('program-id').verify_member(
142
+ first_name: 'George',
143
+ last_name: 'Washington',
144
+ born_on: '1980-01-15',
145
+ employee_id: 'EMP123'
146
+ )
147
+
148
+ result[:status] # => "verified"
149
+ result[:member_id] # => "member-id"
150
+ ```
151
+
152
+ `result[:status]` is one of:
153
+
154
+ | Status | Meaning | `member_id` |
155
+ |---|---|---|
156
+ | `"verified"` | One member matches and is eligible for the program today | The member's ID |
157
+ | `"ineligible"` | One member matches, but isn't eligible for the program today | The member's ID |
158
+ | `"not_found"` | No member matches | `nil` |
159
+ | `"multiple_matches"` | More than one member matches | `nil` |
160
+
161
+ A `verified` member's ID works with `members('member-id').household`. Find, update and household answer 404 for an `ineligible` member's ID.
162
+
163
+ A `nil` or blank field raises `ArgumentError` naming the field, before any request is sent. The message never includes a submitted value. A 404 from the API raises `DataNexus::NotFoundError`; it never comes back as a `not_found` status. `verify_member` is a POST, so a timed-out request raises `DataNexus::TimeoutError` without a retry.
164
+
115
165
  ### Find Member
116
166
 
117
167
  ```ruby
@@ -280,6 +330,10 @@ rescue DataNexus::RateLimitError => e
280
330
  sleep(e.retry_after)
281
331
  rescue DataNexus::APIError => e
282
332
  puts "#{e.status}: #{e.message}"
333
+ rescue DataNexus::TimeoutError
334
+ # timed out, after any retries
335
+ rescue DataNexus::ConnectionError
336
+ # couldn't connect, after any retries
283
337
  end
284
338
  ```
285
339
 
@@ -293,6 +347,8 @@ bundle exec rspec
293
347
  bundle exec rubocop
294
348
  ```
295
349
 
350
+ Every pull request needs an approving review from a code owner listed in [`.github/CODEOWNERS`](.github/CODEOWNERS) before it can merge. An automated review, such as CodeRabbit's, doesn't count, and a push after the approval needs a fresh one.
351
+
296
352
  ## License
297
353
 
298
354
  MIT
@@ -36,16 +36,21 @@ module DataNexus
36
36
  # @param base_url [String, nil] The base URL for the API
37
37
  # @param timeout [Integer, nil] Request timeout in seconds
38
38
  # @param open_timeout [Integer, nil] Connection open timeout in seconds
39
+ # @param ssl_verify [Boolean, nil] Whether to verify SSL certificates
40
+ # @param max_retries [Integer, nil] How many times to retry a timed-out or failed GET, PUT or DELETE
41
+ # (default 2, 0 turns retries off). POST and PATCH requests are never retried.
39
42
  # @param config [Configuration, nil] A pre-built configuration object
40
43
  #
41
44
  # @raise [ConfigurationError] If no API key is provided
42
- def initialize(api_key: nil, base_url: nil, timeout: nil, open_timeout: nil, ssl_verify: nil, config: nil)
45
+ def initialize(api_key: nil, base_url: nil, timeout: nil, open_timeout: nil, ssl_verify: nil, max_retries: nil,
46
+ config: nil)
43
47
  @config = config || build_configuration(
44
48
  api_key: api_key,
45
49
  base_url: base_url,
46
50
  timeout: timeout,
47
51
  open_timeout: open_timeout,
48
- ssl_verify: ssl_verify
52
+ ssl_verify: ssl_verify,
53
+ max_retries: max_retries
49
54
  )
50
55
 
51
56
  validate_configuration!
@@ -95,14 +100,16 @@ module DataNexus
95
100
  # @param timeout [Integer, nil]
96
101
  # @param open_timeout [Integer, nil]
97
102
  # @param ssl_verify [Boolean, nil]
103
+ # @param max_retries [Integer, nil]
98
104
  # @return [Configuration]
99
- def build_configuration(api_key:, base_url:, timeout:, open_timeout:, ssl_verify:)
105
+ def build_configuration(api_key:, base_url:, timeout:, open_timeout:, ssl_verify:, max_retries:)
100
106
  Configuration.new(
101
107
  api_key: api_key,
102
108
  base_url: base_url || Configuration::DEFAULT_BASE_URL,
103
109
  timeout: timeout || Configuration::DEFAULT_TIMEOUT,
104
110
  open_timeout: open_timeout || Configuration::DEFAULT_OPEN_TIMEOUT,
105
- ssl_verify: ssl_verify.nil? ? Configuration::DEFAULT_SSL_VERIFY : ssl_verify
111
+ ssl_verify: ssl_verify.nil? ? Configuration::DEFAULT_SSL_VERIFY : ssl_verify,
112
+ max_retries: max_retries || Configuration::DEFAULT_MAX_RETRIES
106
113
  )
107
114
  end
108
115
 
@@ -31,6 +31,9 @@ module DataNexus
31
31
  # @return [Boolean] Whether to verify SSL certificates
32
32
  attr_accessor :ssl_verify
33
33
 
34
+ # @return [Integer] How many times to retry a timed-out or failed GET, PUT or DELETE
35
+ attr_accessor :max_retries
36
+
34
37
  # Default base URL for the DataNexus API
35
38
  DEFAULT_BASE_URL = 'https://datanexus.darthealth.com'
36
39
 
@@ -43,6 +46,9 @@ module DataNexus
43
46
  # Default SSL verification setting
44
47
  DEFAULT_SSL_VERIFY = true
45
48
 
49
+ # Default number of retries for a timed-out or failed GET, PUT or DELETE
50
+ DEFAULT_MAX_RETRIES = 2
51
+
46
52
  # Initialize a new Configuration instance
47
53
  #
48
54
  # @param api_key [String, nil] The API key for authentication
@@ -50,18 +56,22 @@ module DataNexus
50
56
  # @param timeout [Integer] Request timeout in seconds
51
57
  # @param open_timeout [Integer] Connection open timeout in seconds
52
58
  # @param ssl_verify [Boolean] Whether to verify SSL certificates (set to false for self-signed certs)
59
+ # @param max_retries [Integer] How many times to retry a timed-out or failed GET, PUT or DELETE
60
+ # (0 turns retries off). POST and PATCH requests are never retried.
53
61
  def initialize(
54
62
  api_key: nil,
55
63
  base_url: DEFAULT_BASE_URL,
56
64
  timeout: DEFAULT_TIMEOUT,
57
65
  open_timeout: DEFAULT_OPEN_TIMEOUT,
58
- ssl_verify: DEFAULT_SSL_VERIFY
66
+ ssl_verify: DEFAULT_SSL_VERIFY,
67
+ max_retries: DEFAULT_MAX_RETRIES
59
68
  )
60
69
  @api_key = api_key
61
70
  @base_url = base_url
62
71
  @timeout = timeout
63
72
  @open_timeout = open_timeout
64
73
  @ssl_verify = ssl_verify
74
+ @max_retries = max_retries
65
75
  end
66
76
 
67
77
  # Check if the configuration has valid credentials
@@ -77,7 +77,7 @@ module DataNexus
77
77
 
78
78
  def configure_request(conn)
79
79
  conn.request :json
80
- conn.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
80
+ conn.request :retry, max: config.max_retries, interval: 0.5, backoff_factor: 2,
81
81
  exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
82
82
  end
83
83
 
@@ -22,6 +22,11 @@ module DataNexus
22
22
  # @example Search for members
23
23
  # client.programs("program-uuid").search_members(born_on: "1976-07-04", employee_id: "ABC123")
24
24
  #
25
+ # @example Verify a member
26
+ # client.programs("program-uuid").verify_member(
27
+ # first_name: "george", last_name: "washington", born_on: "1976-07-04", employee_id: "ABC123"
28
+ # )
29
+ #
25
30
  class Programs
26
31
  VALID_SEARCH_COMBINATIONS = [
27
32
  %i[born_on first_name last_name employee_id],
@@ -31,6 +36,8 @@ module DataNexus
31
36
  %i[born_on employee_id]
32
37
  ].freeze
33
38
 
39
+ VERIFY_FIELDS = %i[first_name last_name born_on employee_id].freeze
40
+
34
41
  # @return [Connection] The HTTP connection
35
42
  attr_reader :connection
36
43
 
@@ -125,8 +132,57 @@ module DataNexus
125
132
  connection.post("/api/programs/#{program_id}/members/search", params)
126
133
  end
127
134
 
135
+ # Verify a member of this program
136
+ #
137
+ # Checks whether exactly one member of the program matches all four fields
138
+ # and whether that member is eligible today. The status is one of:
139
+ # - "verified": one member matches and is eligible today
140
+ # - "ineligible": one member matches but isn't eligible today
141
+ # - "not_found": no member matches
142
+ # - "multiple_matches": more than one member matches
143
+ #
144
+ # The member ID is nil unless the status is "verified" or "ineligible".
145
+ #
146
+ # Verify is a POST, so a timed-out request is never retried.
147
+ #
148
+ # @param first_name [String] First name
149
+ # @param last_name [String] Last name
150
+ # @param born_on [String] Date of birth (YYYY-MM-DD)
151
+ # @param employee_id [String] Employee ID of the primary participant
152
+ #
153
+ # @return [Hash] The :status (String) and :member_id (String, nil)
154
+ #
155
+ # @raise [ArgumentError] If a field is nil or blank. The message names the
156
+ # field but never its value.
157
+ # @raise [NotFoundError] If the API answers 404. This is never reported as
158
+ # a "not_found" status.
159
+ #
160
+ # @example
161
+ # result = client.programs("uuid").verify_member(
162
+ # first_name: "george",
163
+ # last_name: "washington",
164
+ # born_on: "1976-07-04",
165
+ # employee_id: "ABC1234"
166
+ # )
167
+ # result[:status] # => "verified"
168
+ # result[:member_id] # => "member-id"
169
+ def verify_member(first_name:, last_name:, born_on:, employee_id:)
170
+ fields = { first_name: first_name, last_name: last_name, born_on: born_on, employee_id: employee_id }
171
+ validate_verify_fields!(fields)
172
+
173
+ response = connection.post("/api/programs/#{program_id}/members/verify", fields)
174
+ response[:data]
175
+ end
176
+
128
177
  private
129
178
 
179
+ def validate_verify_fields!(fields)
180
+ blank = VERIFY_FIELDS.select { |field| fields[field].nil? || fields[field].to_s.strip.empty? }
181
+ return if blank.empty?
182
+
183
+ raise ArgumentError, "Missing or blank verify fields: #{blank.join(', ')}"
184
+ end
185
+
130
186
  def validate_search_params!(params)
131
187
  provided_keys = params.keys.sort
132
188
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module DataNexus
4
- VERSION = '0.3.0'
4
+ VERSION = '0.5.0'
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: data_nexus
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.0
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Alex Kibler
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-10-02 00:00:00.000000000 Z
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: faraday
@@ -45,6 +45,7 @@ executables: []
45
45
  extensions: []
46
46
  extra_rdoc_files: []
47
47
  files:
48
+ - ".github/CODEOWNERS"
48
49
  - ".github/actionlint-matcher.json"
49
50
  - ".github/dependabot.yml"
50
51
  - ".github/workflows/ci.yml"
@@ -89,14 +90,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
89
90
  requirements:
90
91
  - - ">="
91
92
  - !ruby/object:Gem::Version
92
- version: 3.0.0
93
+ version: 3.3.0
93
94
  required_rubygems_version: !ruby/object:Gem::Requirement
94
95
  requirements:
95
96
  - - ">="
96
97
  - !ruby/object:Gem::Version
97
98
  version: '0'
98
99
  requirements: []
99
- rubygems_version: 3.4.19
100
+ rubygems_version: 3.5.22
100
101
  signing_key:
101
102
  specification_version: 4
102
103
  summary: Ruby client for the DataNexus API