data_nexus 0.2.0

data/lib/data_nexus/resources/program_member.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative 'member_consents'
+require_relative 'member_enrollments'
+
+module DataNexus
+  module Resources
+    # Resource for managing a specific member within a program context
+    #
+    # Provides methods for finding, updating, and accessing related resources
+    # for a specific member.
+    #
+    # @example Find a member
+    #   member = client.programs("program-uuid").members("member-id").find
+    #
+    # @example Update a member
+    #   client.programs("program-uuid").members("member-id").update(
+    #     member: { phone_number: "+15551234567" }
+    #   )
+    #
+    # @example Get household members
+    #   household = client.programs("program-uuid").members("member-id").household
+    #
+    # @example Access consents
+    #   client.programs("program-uuid").members("member-id").consents.create(
+    #     consent: { category: "sms", member_response: true, consent_details: {} }
+    #   )
+    #
+    # @example Access enrollments
+    #   client.programs("program-uuid").members("member-id").enrollments.create(
+    #     enrollment: { enrolled_at: "2024-01-01T00:00:00Z" }
+    #   )
+    #
+    class ProgramMember
+      # @return [Connection] The HTTP connection
+      attr_reader :connection
+
+      # @return [String] The program UUID
+      attr_reader :program_id
+
+      # @return [String] The member ID
+      attr_reader :member_id
+
+      # Initialize a new ProgramMember resource
+      #
+      # @param connection [Connection] The HTTP connection
+      # @param program_id [String] The program UUID
+      # @param member_id [String] The member ID
+      def initialize(connection, program_id, member_id)
+        @connection = connection
+        @program_id = program_id
+        @member_id = member_id
+      end
+
+      # Find this member
+      #
+      # @return [Hash] The member data
+      #
+      # @example
+      #   member = client.programs("uuid").members("member-id").find
+      #   puts member[:first_name]
+      def find
+        response = connection.get("#{base_path}/#{member_id}")
+        response[:data]
+      end
+
+      # Update this member's attributes
+      #
+      # @param member [Hash] The member attributes to update
+      # @return [Hash] Response containing :data with the updated member
+      #
+      # @example
+      #   response = client.programs("uuid").members("member-id").update(
+      #     member: { phone_number: "+15551234567" }
+      #   )
+      #   updated_member = response[:data]
+      def update(member:)
+        body = { member: member }
+        connection.patch("#{base_path}/#{member_id}", body)
+      end
+
+      # Get household members for this member
+      #
+      # @return [Array<Hash>] Array of household member data
+      #
+      # @example
+      #   household = client.programs("uuid").members("member-id").household
+      #   household.each { |m| puts "#{m[:first_name]} - #{m[:relationship_type]}" }
+      def household
+        response = connection.get("#{base_path}/#{member_id}/household")
+        response[:data]
+      end
+
+      # Access consents for this member
+      #
+      # @return [MemberConsents] The member consents resource
+      #
+      # @example Create a consent
+      #   client.programs("uuid").members("member-id").consents.create(
+      #     consent: { category: "sms", member_response: true, consent_details: {} }
+      #   )
+      #
+      # @example Find a consent
+      #   client.programs("uuid").members("member-id").consents.find(123)
+      def consents
+        MemberConsents.new(connection, member_id, program_id)
+      end
+
+      # Access enrollments for this member
+      #
+      # @return [MemberEnrollments] The member enrollments resource
+      #
+      # @example Create an enrollment
+      #   client.programs("uuid").members("member-id").enrollments.create(
+      #     enrollment: { enrolled_at: "2024-01-01T00:00:00Z" }
+      #   )
+      #
+      # @example Find an enrollment
+      #   client.programs("uuid").members("member-id").enrollments.find(123)
+      def enrollments
+        MemberEnrollments.new(connection, member_id, program_id)
+      end
+
+      private
+
+      # Base path for program members endpoints
+      #
+      # @return [String]
+      def base_path
+        "/api/programs/#{program_id}/members"
+      end
+    end
+  end
+end

data/lib/data_nexus/resources/program_members.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module DataNexus
+  module Resources
+    # Resource for listing program members
+    #
+    # Provides methods for listing and searching members within a specific program.
+    # For operations on a specific member, use `programs("uuid").members("member-id")`.
+    #
+    # @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
+
+      # @return [String] The program UUID
+      attr_reader :program_id
+
+      # Initialize a new ProgramMembers resource
+      #
+      # @param connection [Connection] The HTTP connection
+      # @param program_id [String] The program UUID
+      def initialize(connection, program_id)
+        @connection = connection
+        @program_id = program_id
+      end
+
+      # List program members with optional filters
+      #
+      # @param first_name [String, nil] Filter by exact first name
+      # @param first_name_prefix [String, nil] Filter by first name prefix (first initial)
+      # @param last_name [String, nil] Filter by exact last name
+      # @param last_name_prefix [String, nil] Filter by last name prefix (min 3 chars)
+      # @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
+      #
+      # @example Basic listing
+      #   collection = client.programs("uuid").members.list
+      #   collection.data.each { |m| puts m[:first_name] }
+      #
+      # @example With filters
+      #   collection = client.programs("uuid").members.list(
+      #     born_on: "1976-07-04",
+      #     last_name_prefix: "was"
+      #   )
+      def list(**params)
+        allowed_params = %i[
+          first_name first_name_prefix
+          last_name last_name_prefix
+          born_on employee_id
+        ]
+
+        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 program members endpoints
+      #
+      # @return [String]
+      def base_path
+        "/api/programs/#{program_id}/members"
+      end
+    end
+  end
+end

data/lib/data_nexus/resources/programs.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'program_member'
+require_relative 'program_members'
+
+module DataNexus
+  module Resources
+    # Proxy for program-scoped resources
+    #
+    # This class provides access to resources that are scoped to a specific program,
+    # such as members, consents, and enrollments.
+    #
+    # @example List program members
+    #   client.programs("program-uuid").members.list
+    #
+    # @example Access a specific member
+    #   client.programs("program-uuid").members("member-id").find
+    #   client.programs("program-uuid").members("member-id").update(member: { phone_number: "..." })
+    #   client.programs("program-uuid").members("member-id").consents.create(...)
+    #   client.programs("program-uuid").members("member-id").enrollments.create(...)
+    #
+    # @example Search for members
+    #   client.programs("program-uuid").search_members(born_on: "1976-07-04", employee_id: "ABC123")
+    #
+    class Programs
+      VALID_SEARCH_COMBINATIONS = [
+        %i[born_on first_name last_name employee_id],
+        %i[born_on first_name last_name],
+        %i[born_on first_name_prefix last_name_prefix employee_id],
+        %i[born_on first_name_prefix last_name_prefix],
+        %i[born_on employee_id]
+      ].freeze
+
+      # @return [Connection] The HTTP connection
+      attr_reader :connection
+
+      # @return [String] The program UUID
+      attr_reader :program_id
+
+      # Initialize a new Programs resource proxy
+      #
+      # @param connection [Connection] The HTTP connection
+      # @param program_id [String] The program UUID
+      def initialize(connection, program_id)
+        @connection = connection
+        @program_id = program_id
+      end
+
+      # Access program members
+      #
+      # When called without an argument, returns a resource for listing members.
+      # When called with a member_id, returns a resource for that specific member.
+      #
+      # @param member_id [String, nil] The member ID (optional)
+      # @return [ProgramMembers] When no member_id provided - for listing members
+      # @return [ProgramMember] When member_id provided - for member-specific operations
+      #
+      # @example List members
+      #   client.programs("uuid").members.list
+      #
+      # @example Access a specific member
+      #   client.programs("uuid").members("member-id").find
+      #
+      # @example Update a member
+      #   client.programs("uuid").members("member-id").update(member: { first_name: "George" })
+      #
+      # @example Access member consents
+      #   client.programs("uuid").members("member-id").consents.create(...)
+      #
+      # @example Access member enrollments
+      #   client.programs("uuid").members("member-id").enrollments.create(...)
+      def members(member_id = nil)
+        if member_id
+          ProgramMember.new(connection, program_id, member_id)
+        else
+          ProgramMembers.new(connection, program_id)
+        end
+      end
+
+      # Search for members within this program
+      #
+      # Returns a bounded result set (max 10 results). Use `more_results` to
+      # determine if additional matches exist beyond what was returned.
+      #
+      # Valid parameter combinations:
+      # - born_on, first_name, last_name, employee_id
+      # - born_on, first_name, last_name
+      # - born_on, first_name_prefix, last_name_prefix, employee_id
+      # - born_on, first_name_prefix, last_name_prefix
+      # - born_on, employee_id
+      #
+      # @param born_on [String] Date of birth (YYYY-MM-DD) - required for all searches
+      # @param first_name [String, nil] Exact first name match
+      # @param first_name_prefix [String, nil] First name prefix (min 1 char)
+      # @param last_name [String, nil] Exact last name match
+      # @param last_name_prefix [String, nil] Last name prefix (min 3 chars)
+      # @param employee_id [String, nil] Employee ID
+      #
+      # @return [Hash] Response with :data (Array) and :more_results (Boolean)
+      #
+      # @raise [ArgumentError] If params don't match a valid search combination
+      #
+      # @example Search by name and DOB
+      #   client.programs("uuid").search_members(
+      #     born_on: "1976-07-04",
+      #     first_name: "george",
+      #     last_name: "washington"
+      #   )
+      #
+      # @example Search by prefix and DOB
+      #   client.programs("uuid").search_members(
+      #     born_on: "1976-07-04",
+      #     first_name_prefix: "g",
+      #     last_name_prefix: "was"
+      #   )
+      #
+      # @example Search by employee ID and DOB
+      #   client.programs("uuid").search_members(
+      #     born_on: "1976-07-04",
+      #     employee_id: "ABC1234"
+      #   )
+      def search_members(**params)
+        validate_search_params!(params)
+
+        connection.post("/api/programs/#{program_id}/members/search", params)
+      end
+
+      private
+
+      def validate_search_params!(params)
+        provided_keys = params.keys.sort
+
+        return if VALID_SEARCH_COMBINATIONS.any? { |combo| combo.sort == provided_keys }
+
+        raise ArgumentError, invalid_search_params_message(provided_keys)
+      end
+
+      def invalid_search_params_message(provided_keys)
+        valid_combos = VALID_SEARCH_COMBINATIONS.map { |c| c.join(', ') }.join("\n  - ")
+
+        "Invalid search parameter combination: #{provided_keys.join(', ')}. " \
+          "Valid combinations are:\n  - #{valid_combos}"
+      end
+    end
+  end
+end

data/lib/data_nexus/version.rb

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

data/lib/data_nexus.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'data_nexus/version'
+require_relative 'data_nexus/errors'
+require_relative 'data_nexus/configuration'
+require_relative 'data_nexus/connection'
+require_relative 'data_nexus/client'
+require_relative 'data_nexus/collection'
+require_relative 'data_nexus/resources/programs'
+require_relative 'data_nexus/resources/program_members'
+
+# Ruby client library for the DataNexus API
+#
+# @example Configure and use the client
+#   client = DataNexus::Client.new(api_key: "your_api_key")
+#   members = client.programs("program-uuid").members.list
+#
+module DataNexus
+  class << self
+    # Global configuration instance
+    #
+    # @return [Configuration]
+    attr_writer :configuration
+
+    # Get the global configuration, initializing if needed
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem globally
+    #
+    # @example
+    #   DataNexus.configure do |config|
+    #     config.api_key = "your_api_key"
+    #     config.base_url = "https://api.datanexus.com"
+    #   end
+    #
+    # @yield [Configuration]
+    def configure
+      yield(configuration)
+    end
+
+    # Reset the global configuration
+    #
+    # @return [Configuration] A fresh configuration instance
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/sig/datanexus.rbs

@@ -0,0 +1,4 @@
+module Datanexus
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: data_nexus
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Alex Kibler
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby gem for interacting with the Dart Health's DataNexus API.
+email:
+- alexkibler@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".mise.local.toml.example"
+- ".mise.toml"
+- ".rubocop.yml"
+- README.md
+- Rakefile
+- lib/data_nexus.rb
+- lib/data_nexus/client.rb
+- lib/data_nexus/collection.rb
+- lib/data_nexus/configuration.rb
+- lib/data_nexus/connection.rb
+- lib/data_nexus/errors.rb
+- 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_member.rb
+- lib/data_nexus/resources/program_members.rb
+- lib/data_nexus/resources/programs.rb
+- lib/data_nexus/version.rb
+- sig/datanexus.rbs
+homepage: https://github.com/DartHealth/datanexus-ruby
+licenses:
+- MIT
+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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Ruby client for the DataNexus API
+test_files: []