data_nexus 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a77e46a3dbaca91a51fa4b1eda5f5f5aa267b1f8c7011d21888de892b19e373
+  data.tar.gz: 91e3d85cdec6629444eaf4c5a7846be3dbaf876ec00b56cefc12b2bac18b473c
+SHA512:
+  metadata.gz: 3fe4cf797a07bdff2cbe1f1a8ad7689f4ea2ff29396c75896e01acf05e41fe88c51f8f7965655565b8e7078c5205e1eb3aa31d5a8bcb31e26133189db958fe51
+  data.tar.gz: 575e20457eca50ebbaf258b9fad1d86210a78337c8bfa04a535457843ce83a73687e21f5629e28a2bdb755a7592a38e4745839a54bb830ded1bae3a8670bc0c2

data/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.0", "3.1", "3.2", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop

data/.mise.local.toml.example

@@ -0,0 +1,14 @@
+# Copy this file to .mise.local.toml and fill in real values
+# This file is gitignored and should contain your local dev/test credentials
+
+[env]
+# The vast majority of these are for testing against a local DataNexus instance and recording VCR cassettes.
+DATANEXUS_API_KEY = "your-real-api-key"
+DATANEXUS_BASE_URL = "https://localhost:4000"
+DATANEXUS_SSL_VERIFY = "false"
+DATANEXUS_TEST_PROGRAM_ID = "your-real-program-id"
+DATANEXUS_TEST_MEMBER_ID = "your-real-member-id"
+DATANEXUS_TEST_CONSENT_ID = "your-real-consent-id"
+DATANEXUS_TEST_ENROLLMENT_ID = "your-real-enrollment-id"
+DATANEXUS_TEST_BORN_ON = "1980-01-15"
+DATANEXUS_TEST_EMPLOYEE_ID = "EMP123"

data/.mise.toml

@@ -0,0 +1,36 @@
+[tools]
+ruby = "3.3"
+
+[tasks.setup]
+description = "Install dependencies"
+run = "bundle install"
+
+[tasks.test]
+description = "Run all tests"
+run = "bundle exec rspec --exclude-pattern 'spec/integration/**/*'"
+depends = ["setup"]
+
+[tasks."test:all"]
+description = "Run all tests including integration"
+run = "bundle exec rspec"
+depends = ["setup"]
+
+[tasks."test:integration"]
+description = "Run integration tests only"
+run = "bundle exec rspec spec/integration/"
+depends = ["setup"]
+
+[tasks.lint]
+description = "Run rubocop"
+run = "bundle exec rubocop"
+depends = ["setup"]
+
+[tasks.fix]
+description = "Run rubocop with auto-fix"
+run = "bundle exec rubocop -a"
+depends = ["setup"]
+
+[tasks.console]
+description = "Start IRB console with gem loaded"
+run = "bundle exec bin/console"
+depends = ["setup"]

data/.rubocop.yml

@@ -0,0 +1,28 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+# Integration tests have different expectations
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/integration/**/*"
+
+RSpec/MultipleExpectations:
+  Exclude:
+    - "spec/integration/**/*"
+
+RSpec/ExampleLength:
+  Exclude:
+    - "spec/integration/**/*"
+
+RSpec/MultipleMemoizedHelpers:
+  Exclude:
+    - "spec/integration/**/*"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/data_nexus/client.rb"

data/README.md

@@ -0,0 +1,268 @@
+# DataNexus
+
+Ruby client for the DataNexus API.
+
+## Installation
+
+Install from GitHub (before gem is published):
+
+```ruby
+gem 'data_nexus', git: 'https://github.com/DartHealth/datanexus-ruby.git', tag: 'v0.1.0'
+```
+
+Or from RubyGems (once published):
+
+```ruby
+gem 'data_nexus'
+```
+
+## Usage
+
+```ruby
+client = DataNexus::Client.new(
+  api_key: ENV['DATANEXUS_API_KEY'],
+  base_url: 'https://api.datanexus.com'  # optional
+)
+```
+
+## Program Members
+
+### List Members
+
+Filters are required. Valid combinations:
+- `born_on` + `employee_id`
+- `born_on` + `first_name` + `last_name`
+- `born_on` + `first_name_prefix` + `last_name_prefix`
+
+```ruby
+collection = client.programs('program-id').members.list(
+  born_on: '1980-01-15',
+  employee_id: 'EMP123'
+)
+
+collection.data.each do |member|
+  puts "#{member[:first_name]} #{member[:last_name]}"
+end
+```
+
+### 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.
+
+Valid parameter combinations:
+- `born_on` + `employee_id`
+- `born_on` + `first_name` + `last_name`
+- `born_on` + `first_name` + `last_name` + `employee_id`
+- `born_on` + `first_name_prefix` + `last_name_prefix`
+- `born_on` + `first_name_prefix` + `last_name_prefix` + `employee_id`
+
+```ruby
+# Search by employee ID and DOB
+result = client.programs('program-id').search_members(
+  born_on: '1980-01-15',
+  employee_id: 'EMP123'
+)
+
+result[:data].each do |member|
+  puts "#{member[:first_name]} #{member[:last_name]}"
+end
+
+puts "More results available" if result[:more_results]
+
+# Search by name and DOB
+result = client.programs('program-id').search_members(
+  born_on: '1980-01-15',
+  first_name: 'George',
+  last_name: 'Washington'
+)
+
+# Search by name prefix and DOB
+result = client.programs('program-id').search_members(
+  born_on: '1980-01-15',
+  first_name_prefix: 'G',
+  last_name_prefix: 'Was'
+)
+```
+
+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: 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
+member = client.programs('program-id').members('member-id').find
+puts member[:first_name]
+```
+
+### Update Member
+
+```ruby
+response = client.programs('program-id').members('member-id').update(
+  member: { phone_number: '+15551234567' }
+)
+```
+
+### Household Members
+
+```ruby
+household = client.programs('program-id').members('member-id').household
+household.each { |member| puts member[:first_name] }
+```
+
+### Member Consents
+
+#### Create Consent
+
+```ruby
+response = client.programs('program-id').members('member-id').consents.create(
+  consent: {
+    category: 'sms',
+    member_response: true,
+    consent_details: { sms_phone_number: '+15558675309' }
+  }
+)
+# program_id is automatically injected
+```
+
+#### Find Consent
+
+```ruby
+consent = client.programs('program-id').members('member-id').consents.find(123)
+puts consent[:category]
+```
+
+#### Update Consent
+
+```ruby
+response = client.programs('program-id').members('member-id').consents.update(123,
+  consent: { member_response: false }
+)
+```
+
+#### Delete Consent
+
+```ruby
+client.programs('program-id').members('member-id').consents.delete(123)
+```
+
+### Member Enrollments
+
+#### Create Enrollment
+
+```ruby
+response = client.programs('program-id').members('member-id').enrollments.create(
+  enrollment: {
+    enrolled_at: '2024-01-01T00:00:00Z',
+    expires_at: '2025-01-01T00:00:00Z'
+  }
+)
+# program_id is automatically injected
+```
+
+#### Find Enrollment
+
+```ruby
+enrollment = client.programs('program-id').members('member-id').enrollments.find(123)
+puts enrollment[:enrolled_at]
+```
+
+#### Update Enrollment
+
+```ruby
+response = client.programs('program-id').members('member-id').enrollments.update(123,
+  enrollment: { expires_at: '2026-01-01T00:00:00Z' }
+)
+```
+
+#### Delete Enrollment
+
+```ruby
+client.programs('program-id').members('member-id').enrollments.delete(123)
+```
+
+## Top-Level Members
+
+You can also access members without a program scope:
+
+### List Members
+
+```ruby
+collection = client.members.list(
+  first_name: 'George',
+  last_name: 'Washington',
+  born_on: '1976-07-04'
+)
+
+# Filter by program eligibility
+collection = client.members.list(program_id: 'program-uuid')
+
+# Filter by update time
+collection = client.members.list(updated_since: '2024-01-01T00:00:00Z')
+
+# Pagination
+collection = client.members.list(first: 50, after: 'cursor')
+```
+
+### Find Member
+
+```ruby
+member = client.members.find('member-id')
+puts member[:first_name]
+```
+
+### Update Member
+
+```ruby
+response = client.members.update('member-id',
+  member: { phone_number: '+15551234567' }
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.programs('id').members('id').find
+rescue DataNexus::AuthenticationError
+  # 401
+rescue DataNexus::NotFoundError
+  # 404
+rescue DataNexus::UnprocessableEntityError
+  # 422
+rescue DataNexus::RateLimitError => e
+  sleep(e.retry_after)
+rescue DataNexus::APIError => e
+  puts "#{e.status}: #{e.message}"
+end
+```
+
+## Development
+
+```bash
+cp .mise.local.toml.example .mise.local.toml
+# Edit .mise.local.toml with your test credentials
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/data_nexus/client.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative 'configuration'
+require_relative 'connection'
+require_relative 'resources/members'
+require_relative 'resources/programs'
+
+module DataNexus
+  # Main client for interacting with the DataNexus API
+  #
+  # @example Create a client with explicit configuration
+  #   client = DataNexus::Client.new(api_key: "your_api_key")
+  #
+  # @example Create a client with a configuration object
+  #   config = DataNexus::Configuration.new(api_key: "your_api_key")
+  #   client = DataNexus::Client.new(config: config)
+  #
+  # @example Access program members
+  #   client.programs("program-uuid").members.list
+  #   client.programs("program-uuid").members("member-id").find
+  #
+  class Client
+    # @return [Configuration] The client configuration
+    attr_reader :config
+
+    # @return [Connection] The HTTP connection
+    attr_reader :connection
+
+    # Initialize a new Client
+    #
+    # @param api_key [String, nil] The API key for authentication
+    # @param base_url [String, nil] The base URL for the API
+    # @param timeout [Integer, nil] Request timeout in seconds
+    # @param open_timeout [Integer, nil] Connection open timeout in seconds
+    # @param config [Configuration, nil] A pre-built configuration object
+    #
+    # @raise [ConfigurationError] If no API key is provided
+    def initialize(api_key: nil, base_url: nil, timeout: nil, open_timeout: nil, ssl_verify: nil, config: nil)
+      @config = config || build_configuration(
+        api_key: api_key,
+        base_url: base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        ssl_verify: ssl_verify
+      )
+
+      validate_configuration!
+
+      @connection = Connection.new(@config)
+    end
+
+    # Access top-level member resources
+    #
+    # @return [Resources::Members] A members resource
+    #
+    # @example
+    #   client.members.list
+    #   client.members.find("member-id")
+    def members
+      Resources::Members.new(connection)
+    end
+
+    # Access program-scoped resources
+    #
+    # @param program_id [String] The program UUID
+    # @return [Resources::Programs] A program resource proxy
+    #
+    # @example
+    #   client.programs("uuid").members.list
+    def programs(program_id)
+      Resources::Programs.new(connection, program_id)
+    end
+
+    private
+
+    # Build a configuration from individual parameters
+    #
+    # @param api_key [String, nil]
+    # @param base_url [String, nil]
+    # @param timeout [Integer, nil]
+    # @param open_timeout [Integer, nil]
+    # @param ssl_verify [Boolean, nil]
+    # @return [Configuration]
+    def build_configuration(api_key:, base_url:, timeout:, open_timeout:, ssl_verify:)
+      Configuration.new(
+        api_key: api_key,
+        base_url: base_url || Configuration::DEFAULT_BASE_URL,
+        timeout: timeout || Configuration::DEFAULT_TIMEOUT,
+        open_timeout: open_timeout || Configuration::DEFAULT_OPEN_TIMEOUT,
+        ssl_verify: ssl_verify.nil? ? Configuration::DEFAULT_SSL_VERIFY : ssl_verify
+      )
+    end
+
+    # Validate that the configuration is complete
+    #
+    # @raise [ConfigurationError] If the configuration is invalid
+    def validate_configuration!
+      return if @config.valid?
+
+      raise ConfigurationError, 'API key is required. Pass api_key: or provide a configured Configuration object.'
+    end
+  end
+end

data/lib/data_nexus/collection.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module DataNexus
+  # Wrapper for paginated API responses
+  #
+  # Provides convenience methods for accessing data and navigating through pages.
+  # The underlying data remains as hashes - this class just adds pagination helpers.
+  #
+  # @example Accessing data
+  #   collection = client.programs('uuid').members.list
+  #   collection.data.each { |member| puts member[:first_name] }
+  #
+  # @example Manual pagination
+  #   collection = client.programs('uuid').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|
+  #     page.data.each { |member| puts member[:first_name] }
+  #   end
+  #
+  class Collection
+    # @return [Array<Hash>] The records in this page
+    attr_reader :data
+
+    # @return [String, nil] Cursor for the start of this page
+    attr_reader :start_cursor
+
+    # @return [String, nil] Cursor for the end of this page
+    attr_reader :end_cursor
+
+    # Initialize a new Collection
+    #
+    # @param response [Hash] The raw API response
+    # @param resource [Object] The resource instance that made the request
+    # @param params [Hash] The params used for the original request
+    def initialize(response, resource:, params:)
+      @data = response[:data] || []
+      @start_cursor = response[:start_cursor]
+      @end_cursor = response[:end_cursor]
+      @resource = resource
+      @params = params
+    end
+
+    # Check if there's a next page of results
+    #
+    # @return [Boolean]
+    def next_page?
+      !end_cursor.nil? && !end_cursor.empty?
+    end
+
+    # Fetch the next page of results
+    #
+    # @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)
+    end
+
+    # Check if there's a previous page of results
+    #
+    # @return [Boolean]
+    def previous_page?
+      !start_cursor.nil? && !start_cursor.empty?
+    end
+
+    # Fetch the previous page of results
+    #
+    # @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)
+    end
+
+    # Iterate through all pages starting from this one
+    #
+    # @yield [Collection] Each page of results
+    # @return [Enumerator] If no block given
+    def each_page
+      return enum_for(:each_page) unless block_given?
+
+      page = self
+      while page
+        yield page
+        page = page.next_page
+      end
+    end
+
+    # Iterate through all records across all pages
+    #
+    # @yield [Hash] Each record
+    # @return [Enumerator] If no block given
+    def each_record(&block)
+      return enum_for(:each_record) unless block_given?
+
+      each_page do |page|
+        page.data.each(&block)
+      end
+    end
+
+    alias each each_record
+
+    # @return [Boolean] Whether this page has any records
+    def empty?
+      data.empty?
+    end
+
+    # @return [Integer] Number of records in this page
+    def size
+      data.size
+    end
+
+    alias length size
+  end
+end

data/lib/data_nexus/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module DataNexus
+  # Configuration class for storing API credentials and settings
+  #
+  # @example Configure the client globally
+  #   DataNexus.configure do |config|
+  #     config.api_key = "your_api_key"
+  #     config.base_url = "https://api.datanexus.com"
+  #   end
+  #
+  # @example Create a configuration instance
+  #   config = DataNexus::Configuration.new(
+  #     api_key: "your_api_key",
+  #     base_url: "https://api.datanexus.com"
+  #   )
+  #
+  class Configuration
+    # @return [String, nil] The API key for authentication
+    attr_accessor :api_key
+
+    # @return [String] The base URL for the DataNexus API
+    attr_accessor :base_url
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Connection open timeout in seconds
+    attr_accessor :open_timeout
+
+    # @return [Boolean] Whether to verify SSL certificates
+    attr_accessor :ssl_verify
+
+    # Default base URL for the DataNexus API
+    DEFAULT_BASE_URL = 'https://api.datanexus.com'
+
+    # Default request timeout in seconds
+    DEFAULT_TIMEOUT = 30
+
+    # Default connection open timeout in seconds
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    # Default SSL verification setting
+    DEFAULT_SSL_VERIFY = true
+
+    # Initialize a new Configuration instance
+    #
+    # @param api_key [String, nil] The API key for authentication
+    # @param base_url [String] The base URL for the API
+    # @param timeout [Integer] Request timeout in seconds
+    # @param open_timeout [Integer] Connection open timeout in seconds
+    # @param ssl_verify [Boolean] Whether to verify SSL certificates (set to false for self-signed certs)
+    def initialize(
+      api_key: nil,
+      base_url: DEFAULT_BASE_URL,
+      timeout: DEFAULT_TIMEOUT,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      ssl_verify: DEFAULT_SSL_VERIFY
+    )
+      @api_key = api_key
+      @base_url = base_url
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @ssl_verify = ssl_verify
+    end
+
+    # Check if the configuration has valid credentials
+    #
+    # @return [Boolean] true if api_key is present
+    def valid?
+      !api_key.nil? && !api_key.empty?
+    end
+  end
+end