data_nexus 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27c91c699abd23dd3463ae2dbe82840f32cb2d0dc8753caec22734c86fda1fd5
-  data.tar.gz: 85bf87c4cad24a20ae307b996cdafbcc5827a3f0f8b1f375b4b506d7a28d0715
+  metadata.gz: 11502860850ccde0aa9b28ec2770d583d716af03d2d8a2cba9beb60383933dae
+  data.tar.gz: a9e2a9215fb714a6a015d629de69dc112d55697f8d1c227a61689b2f8fbe3c56
 SHA512:
-  metadata.gz: fb51987bebd0709461f56093be6c0d3b4ab9dbb151f7f2c5db8c6399050d5f8cf168d1ae4e5bf3b31129ccc838e118c1dce23df78fd41f2c8a3eb0058eed23a3
-  data.tar.gz: 7ff0c3784d400e5b28e2fd1ea2d51e27162d8fa759fbda03b05b9aa21e328401a0cb88f5173dfa3c4e8e0372f5c48872c1870bdcff0b34c9d3cf0fc4ca0ab4f5
+  metadata.gz: af48c59e9c0f360b3ec058721e80cfc36f7c6067420097c86c60129d7455e92c06601185e5a40df232b2d1b2c08a05137ed2231b470c8defb52c7eddf65246ed
+  data.tar.gz: e6f73e656deb92723c946d49299019081eedddacb866e608c961107cf92421396f790ca2329a00abd9223b06e5a9c5a364b326cba79a5e4ae8d3cbc530d2a0e2

data/.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Ruby ${{ matrix.ruby-version }}
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@e8944e80fb94b20106697132f8c20c665fab29e9 # v1.325.0
         with:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
@@ -40,7 +40,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@e8944e80fb94b20106697132f8c20c665fab29e9 # v1.325.0
         with:
           ruby-version: "3.2"
           bundler-cache: true

data/.github/workflows/release.yml

@@ -37,7 +37,7 @@ jobs:
       # cache, so a restored cache could hand the release poisoned
       # dependencies. A fresh install costs seconds.
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@e8944e80fb94b20106697132f8c20c665fab29e9 # v1.325.0
         with:
           ruby-version: "3.2"
 

data/AGENTS.md

@@ -14,6 +14,7 @@
   - `collection.rb` - Collection handling
   - `errors.rb` - Custom error classes
   - `version.rb` - Gem version (bump here for releases)
+- `CHANGELOG.md` - User-facing changes per release
 - `spec/` - RSpec tests
 - `.github/workflows/` - CI and release automation
 
@@ -35,11 +36,13 @@ Pin every action to a full commit SHA, with the exact version in a comment; `pin
 
 ## Releasing
 
-1. Bump the version in `lib/data_nexus/version.rb`
+1. Bump the version in `lib/data_nexus/version.rb`. In `CHANGELOG.md`, rename `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD`, add a new empty `## [Unreleased]` section above it, and update the links at the bottom: `[Unreleased]` compares `vX.Y.Z...HEAD`, and a new `[X.Y.Z]` link compares the previous tag to `vX.Y.Z`
 2. Merge to `main`
-3. Create a GitHub Release with tag `vX.Y.Z` matching the version
+3. Create a GitHub Release with tag `vX.Y.Z` matching the version. Paste that version's `CHANGELOG.md` section above GitHub's generated pull request list
 4. The release workflow runs tests, verifies the version/tag match, builds, and pushes to RubyGems
 
+Any pull request that changes shipped behavior (anything under `lib/`, or runtime dependencies in the gemspec) adds an entry under `[Unreleased]` in `CHANGELOG.md`.
+
 ## When to Suggest a Release
 
 Only suggest a release when there are meaningful changes to the gem's shipped code (anything under `lib/`). Changes that do NOT warrant a release on their own:

data/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+Notable changes to the `data_nexus` gem. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the gem uses [Semantic Versioning](https://semver.org/).
+
+Dependency bumps, CI changes and test-only changes are left out. From 0.2.0 on, the [GitHub releases](https://github.com/DartHealth/datanexus-ruby/releases) list every merged pull request.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-02
+
+### Added
+
+- `client.programs.list` lists the programs your API key can see, sorted by name. Each program has an `:id` and a `:name`. It pages with `first`, `after`, `before` and `last` (25 programs per page by default), and `name:` filters by program name, ignoring case, so an app can look up a program ID without leaving the gem ([sc-6843](https://app.shortcut.com/dart/story/6843)):
+
+  ```ruby
+  program = client.programs.list(name: 'Example Program').data.first
+  raise "Program not found: Example Program" unless program
+
+  client.programs(program[:id]).search_members(born_on: '1980-01-15', employee_id: 'EMP123')
+  ```
+
+- `Collection#next_page?` and `#previous_page?` return `false` when the response's `has_next_page` or `has_previous_page` is `false`, so iterating a list that sends those flags (such as `client.programs.list`) stops without requesting an empty page.
+
+### Changed
+
+- `client.programs` with no argument now returns the program list instead of raising `ArgumentError`. `client.programs('program-id')` is unchanged.
+- `client.programs(nil)` also returns the program list. Code that passes a missing program ID now fails in the gem with `NoMethodError` (for example on `.members`) instead of sending a request to `/api/programs//members`.
+
+### Fixed
+
+- `Collection#next_page` and `#previous_page` return `nil` when the API sends back the same page, so `each`, `each_record` and `each_page` stop instead of looping forever. Program member lists (`client.programs('program-id').members.list`) were affected: the API returns them as a single page that still carries a cursor. Iterating one now stops after that page.
+
+## [0.2.2] - 2026-09-18
+
+### Changed
+
+- Releases are published to RubyGems with trusted publishing. The gem's code is unchanged from 0.2.1.
+
+## [0.2.1] - 2026-02-04
+
+### Fixed
+
+- The default `base_url` is now `https://datanexus.darthealth.com`. It was `https://api.datanexus.com`.
+
+## [0.2.0] - 2026-02-04
+
+### Added
+
+- `client.programs('program-id').search_members(...)` searches a program's members by date of birth plus name, name prefix or employee ID. It returns up to 10 results and a `more_results` flag, and raises `ArgumentError` for an invalid parameter combination.
+
+## [0.1.0] - 2026-01-14
+
+Tagged but not published to RubyGems. 0.2.0 was the first published version and includes everything below.
+
+### Added
+
+- `DataNexus::Client` with API key authentication, timeouts, SSL verification and automatic retries.
+- Members: `client.members.list`, `find` and `update`.
+- Program members: `client.programs('program-id').members.list`, and `find`, `update` and `household` on a single member.
+- Member consents and enrollments: `create`, `find`, `update` and `delete`.
+- `DataNexus::Collection` for cursor-paginated lists (`next_page`, `previous_page`, `each_page`, `each`).
+- Error classes for API errors (`AuthenticationError`, `NotFoundError`, `RateLimitError` and others) and connection errors.
+
+[Unreleased]: https://github.com/DartHealth/datanexus-ruby/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/DartHealth/datanexus-ruby/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/DartHealth/datanexus-ruby/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/DartHealth/datanexus-ruby/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/DartHealth/datanexus-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/DartHealth/datanexus-ruby/tree/v0.1.0

data/README.md

@@ -17,6 +17,36 @@ client = DataNexus::Client.new(
 )
 ```
 
+## Programs
+
+### List Programs
+
+Lists the programs your API key can see, sorted by name. Each program has an `:id` and a `:name`.
+
+```ruby
+collection = client.programs.list
+
+collection.data.each do |program|
+  puts "#{program[:id]} #{program[:name]}"
+end
+```
+
+A page holds 25 programs by default. `list` takes `first`, `after`, `before` and `last`, and `each` reads every page. See [Pagination](#pagination).
+
+### Look Up a Program by Name
+
+Every program-scoped call needs a program ID. To start from a program's name, filter by `name`. The match ignores case and surrounding whitespace:
+
+```ruby
+program = client.programs.list(name: 'Example Program').data.first
+raise "Program not found: Example Program" unless program
+
+client.programs(program[:id]).search_members(
+  born_on: '1980-01-15',
+  employee_id: 'EMP123'
+)
+```
+
 ## Program Members
 
 ### List Members
@@ -37,6 +67,8 @@ collection.data.each do |member|
 end
 ```
 
+Note: Program member lists return a single page of up to 25 members. See [Pagination](#pagination).
+
 ### Search Members
 
 Search for members within a program. Returns a bounded result set (max 10 results) with a `more_results` flag indicating if additional matches exist.
@@ -76,26 +108,10 @@ result = client.programs('program-id').search_members(
 )
 ```
 
-Note: Unlike `list`, `search_members` does not support pagination. It returns up to 10 results with a `more_results` boolean. An `ArgumentError` will be raised if an invalid parameter combination is provided.
+Note: `search_members` does not support pagination. It returns up to 10 results with a `more_results` boolean. An `ArgumentError` will be raised if an invalid parameter combination is provided.
 
 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.
 
-### Pagination
-
-```ruby
-collection.each_page do |page|
-  page.data.each { |member| process(member) }
-end
-
-# Or iterate all records directly
-collection.each { |member| process(member) }
-
-# Manual pagination
-if collection.next_page?
-  next_collection = collection.next_page
-end
-```
-
 ### Find Member
 
 ```ruby
@@ -227,6 +243,28 @@ response = client.members.update('member-id',
 )
 ```
 
+## Pagination
+
+`list` methods return a `DataNexus::Collection`, one page of records plus cursors. Program lists (`client.programs.list`) and top-level member lists (`client.members.list`) page with `first`, `after`, `before` and `last`:
+
+```ruby
+collection = client.members.list(first: 50)
+
+collection.each_page do |page|
+  page.data.each { |member| process(member) }
+end
+
+# Or iterate all records directly
+collection.each { |member| process(member) }
+
+# Manual pagination
+if collection.next_page?
+  next_collection = collection.next_page
+end
+```
+
+Note: Program member lists (`client.programs('program-id').members.list`) currently return a single page of up to 25 records. `each` and `each_page` stop after that page. `next_page?` can still return `true` for these lists, and `next_page` then returns `nil`.
+
 ## Error Handling
 
 ```ruby

data/lib/data_nexus/client.rb

@@ -3,6 +3,7 @@
 require_relative 'configuration'
 require_relative 'connection'
 require_relative 'resources/members'
+require_relative 'resources/program_list'
 require_relative 'resources/programs'
 
 module DataNexus
@@ -15,6 +16,9 @@ module DataNexus
   #   config = DataNexus::Configuration.new(api_key: "your_api_key")
   #   client = DataNexus::Client.new(config: config)
   #
+  # @example List programs
+  #   client.programs.list.each { |program| puts "#{program[:id]} #{program[:name]}" }
+  #
   # @example Access program members
   #   client.programs("program-uuid").members.list
   #   client.programs("program-uuid").members("member-id").find
@@ -60,15 +64,26 @@ module DataNexus
       Resources::Members.new(connection)
     end
 
-    # Access program-scoped resources
+    # Access programs
     #
-    # @param program_id [String] The program UUID
-    # @return [Resources::Programs] A program resource proxy
+    # When called without an argument, returns a resource for listing programs.
+    # When called with a program_id, returns a proxy for program-scoped resources.
     #
-    # @example
+    # @param program_id [String, nil] The program UUID (optional)
+    # @return [Resources::ProgramList] When no program_id provided - for listing programs
+    # @return [Resources::Programs] When program_id provided - a program resource proxy
+    #
+    # @example List programs
+    #   client.programs.list
+    #
+    # @example Access program members
     #   client.programs("uuid").members.list
-    def programs(program_id)
-      Resources::Programs.new(connection, program_id)
+    def programs(program_id = nil)
+      if program_id
+        Resources::Programs.new(connection, program_id)
+      else
+        Resources::ProgramList.new(connection)
+      end
     end
 
     private

data/lib/data_nexus/collection.rb

@@ -7,18 +7,18 @@ module DataNexus
   # The underlying data remains as hashes - this class just adds pagination helpers.
   #
   # @example Accessing data
-  #   collection = client.programs('uuid').members.list
+  #   collection = client.members.list
   #   collection.data.each { |member| puts member[:first_name] }
   #
   # @example Manual pagination
-  #   collection = client.programs('uuid').members.list(first: 50)
+  #   collection = client.members.list(first: 50)
   #   while collection
   #     process(collection.data)
   #     collection = collection.next_page
   #   end
   #
   # @example Block pagination
-  #   client.programs('uuid').members.list(first: 50).each_page do |page|
+  #   client.members.list(first: 50).each_page do |page|
   #     page.data.each { |member| puts member[:first_name] }
   #   end
   #
@@ -41,40 +41,60 @@ module DataNexus
       @data = response[:data] || []
       @start_cursor = response[:start_cursor]
       @end_cursor = response[:end_cursor]
+      @has_next_page = response[:has_next_page]
+      @has_previous_page = response[:has_previous_page]
       @resource = resource
       @params = params
     end
 
     # Check if there's a next page of results
     #
+    # Uses the response's has_next_page flag when the endpoint sends one,
+    # and otherwise assumes a page with an end_cursor may have a next page.
+    #
     # @return [Boolean]
     def next_page?
+      return false if @has_next_page == false
+
       !end_cursor.nil? && !end_cursor.empty?
     end
 
     # Fetch the next page of results
     #
+    # Returns nil if the API responds with this same page again (an endpoint
+    # that ignores the cursor), so iterating all pages always terminates.
+    #
     # @return [Collection, nil] The next page, or nil if no more pages
     def next_page
       return nil unless next_page?
 
-      @resource.list(**@params, after: end_cursor)
+      page = @resource.list(**@params, after: end_cursor)
+      page unless page&.end_cursor == end_cursor
     end
 
     # Check if there's a previous page of results
     #
+    # Uses the response's has_previous_page flag when the endpoint sends one,
+    # and otherwise assumes a page with a start_cursor may have a previous page.
+    #
     # @return [Boolean]
     def previous_page?
+      return false if @has_previous_page == false
+
       !start_cursor.nil? && !start_cursor.empty?
     end
 
     # Fetch the previous page of results
     #
+    # Returns nil if the API responds with this same page again (an endpoint
+    # that ignores the cursor).
+    #
     # @return [Collection, nil] The previous page, or nil if no more pages
     def previous_page
       return nil unless previous_page?
 
-      @resource.list(**@params, before: start_cursor)
+      page = @resource.list(**@params, before: start_cursor)
+      page unless page&.start_cursor == start_cursor
     end
 
     # Iterate through all pages starting from this one

data/lib/data_nexus/resources/program_list.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module DataNexus
+  module Resources
+    # Resource for listing the programs visible to the API key
+    #
+    # For operations on a specific program, use `programs("uuid")`.
+    #
+    # @example List programs
+    #   collection = client.programs.list
+    #   collection.data.each { |program| puts "#{program[:id]} #{program[:name]}" }
+    #
+    # @example Look up a program ID by name
+    #   program = client.programs.list(name: "Example Program").data.first
+    #   raise "Program not found" unless program
+    #   client.programs(program[:id]).search_members(born_on: "1976-07-04", employee_id: "ABC123")
+    #
+    class ProgramList
+      # @return [Connection] The HTTP connection
+      attr_reader :connection
+
+      # Initialize a new ProgramList resource
+      #
+      # @param connection [Connection] The HTTP connection
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # List programs, sorted by name
+      #
+      # A page holds 25 programs unless you pass `first` or `last`.
+      #
+      # @param name [String, nil] Return only programs with this name, ignoring case
+      # @param after [String, nil] Cursor for next group of records
+      # @param before [String, nil] Cursor for previous group of records
+      # @param first [Integer, nil] Number of records to fetch after cursor
+      # @param last [Integer, nil] Number of records to fetch before cursor
+      #
+      # @return [Collection] Collection of programs, each with :id and :name
+      #
+      # @example Basic listing
+      #   collection = client.programs.list
+      #   collection.data.each { |p| puts p[:name] }
+      #
+      # @example Filter by name
+      #   collection = client.programs.list(name: "Example Program")
+      #
+      # @example Iterate over every program, across pages
+      #   client.programs.list.each { |p| puts p[:name] }
+      def list(**params)
+        allowed_params = %i[after before first last name]
+
+        query_params = params.slice(*allowed_params).compact
+        response = connection.get(base_path, query_params)
+        Collection.new(response, resource: self, params: query_params)
+      end
+
+      private
+
+      # Base path for programs endpoints
+      #
+      # @return [String]
+      def base_path
+        '/api/programs'
+      end
+    end
+  end
+end

data/lib/data_nexus/resources/program_members.rb

@@ -7,16 +7,15 @@ module DataNexus
     # Provides methods for listing and searching members within a specific program.
     # For operations on a specific member, use `programs("uuid").members("member-id")`.
     #
+    # Note: `list` currently returns a single page of up to 25 members, and
+    # iteration stops after that page.
+    #
     # @example List members with filters
     #   client.programs("uuid").members.list(
     #     first_name: "george",
     #     born_on: "1976-07-04"
     #   )
     #
-    # @example Paginate through members
-    #   collection = client.programs("uuid").members.list(first: 50)
-    #   collection.each_page { |page| process(page.data) }
-    #
     class ProgramMembers
       # @return [Connection] The HTTP connection
       attr_reader :connection
@@ -42,7 +41,7 @@ module DataNexus
       # @param born_on [String, nil] Filter by date of birth (YYYY-MM-DD)
       # @param employee_id [String, nil] Filter by employee ID
       #
-      # @return [Collection] Paginated collection of members
+      # @return [Collection] The first page of matching members
       #
       # @example Basic listing
       #   collection = client.programs("uuid").members.list

data/lib/data_nexus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataNexus
-  VERSION = '0.2.2'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_nexus
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Kibler
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -54,6 +54,7 @@ files:
 - ".mise.toml"
 - ".rubocop.yml"
 - AGENTS.md
+- CHANGELOG.md
 - CLAUDE.md
 - README.md
 - Rakefile
@@ -66,6 +67,7 @@ files:
 - lib/data_nexus/resources/member_consents.rb
 - lib/data_nexus/resources/member_enrollments.rb
 - lib/data_nexus/resources/members.rb
+- lib/data_nexus/resources/program_list.rb
 - lib/data_nexus/resources/program_member.rb
 - lib/data_nexus/resources/program_members.rb
 - lib/data_nexus/resources/programs.rb
@@ -77,7 +79,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/DartHealth/datanexus-ruby
   source_code_uri: https://github.com/DartHealth/datanexus-ruby
-  changelog_uri: https://github.com/DartHealth/datanexus-ruby/releases
+  changelog_uri: https://github.com/DartHealth/datanexus-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []