data_nexus 0.2.0

data/lib/data_nexus/connection.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+
+module DataNexus
+  # HTTP connection wrapper using Faraday
+  #
+  # Handles authentication, request/response processing, and error handling.
+  #
+  class Connection
+    # @return [Configuration] The connection configuration
+    attr_reader :config
+
+    # Initialize a new Connection
+    #
+    # @param config [Configuration] The configuration object
+    def initialize(config)
+      @config = config
+    end
+
+    # Perform a GET request
+    #
+    # @param path [String] The API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed JSON response
+    def get(path, params = {})
+      request(:get, path, params)
+    end
+
+    # Perform a POST request
+    #
+    # @param path [String] The API endpoint path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed JSON response
+    def post(path, body = {})
+      request(:post, path, body)
+    end
+
+    # Perform a PATCH request
+    #
+    # @param path [String] The API endpoint path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed JSON response
+    def patch(path, body = {})
+      request(:patch, path, body)
+    end
+
+    # Perform a DELETE request
+    #
+    # @param path [String] The API endpoint path
+    # @return [Hash] Parsed JSON response (empty on 204 No Content)
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    # Build the Faraday connection
+    #
+    # @return [Faraday::Connection]
+    def faraday
+      @faraday ||= Faraday.new(url: config.base_url, ssl: ssl_options) do |conn|
+        configure_request(conn)
+        configure_headers(conn)
+        configure_timeouts(conn)
+
+        conn.response :raise_error
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def ssl_options
+      { verify: config.ssl_verify }
+    end
+
+    def configure_request(conn)
+      conn.request :json
+      conn.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                           exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
+    end
+
+    def configure_headers(conn)
+      conn.headers['Authorization'] = "apikey #{config.api_key}"
+      conn.headers['Content-Type'] = 'application/json'
+      conn.headers['Accept'] = 'application/json'
+      conn.headers['User-Agent'] = "data-nexus-ruby/#{DataNexus::VERSION}"
+    end
+
+    def configure_timeouts(conn)
+      conn.options.timeout = config.timeout
+      conn.options.open_timeout = config.open_timeout
+    end
+
+    # Perform an HTTP request
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :patch)
+    # @param path [String] The API endpoint path
+    # @param params_or_body [Hash] Query params (GET) or body (POST/PATCH)
+    # @return [Hash] Parsed JSON response
+    def request(method, path, params_or_body = {})
+      response = faraday.public_send(method, path, params_or_body)
+      parse_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      handle_error_response(e)
+    end
+
+    # Parse the response body as JSON
+    #
+    # @param response [Faraday::Response]
+    # @return [Hash]
+    def parse_response(response)
+      return {} if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError
+      { raw_body: response.body }
+    end
+
+    # Handle error responses and raise appropriate exceptions
+    #
+    # @param error [Faraday::Error]
+    # @raise [APIError] The appropriate error subclass
+    def handle_error_response(error)
+      status, body, message = extract_error_details(error)
+      error_class = HTTP_STATUS_ERRORS[status] || APIError
+
+      raise_api_error(error_class, message, status, body, error.response)
+    end
+
+    def extract_error_details(error)
+      status = error.response&.dig(:status)
+      body = parse_error_body(error.response&.dig(:body))
+      message = extract_error_message(body, error.message)
+
+      [status, body, message]
+    end
+
+    def raise_api_error(error_class, message, status, body, response)
+      if error_class == RateLimitError
+        retry_after = response&.dig(:headers, 'retry-after')&.to_i
+        raise error_class.new(message, status: status, response_body: body, retry_after: retry_after)
+      end
+
+      raise error_class.new(message, status: status, response_body: body)
+    end
+
+    # Parse error response body
+    #
+    # @param body [String, nil]
+    # @return [Hash, nil]
+    def parse_error_body(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      { raw_body: body }
+    end
+
+    # Extract a human-readable error message
+    #
+    # @param body [Hash, nil]
+    # @param default [String]
+    # @return [String]
+    def extract_error_message(body, default)
+      return default unless body.is_a?(Hash)
+
+      body[:error] || body[:message] || body[:errors]&.first || default
+    end
+  end
+end

data/lib/data_nexus/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module DataNexus
+  # Base error class for all DataNexus errors
+  class Error < StandardError
+    # @return [Integer, nil] HTTP status code if applicable
+    attr_reader :status
+
+    # @return [Hash, nil] Response body if available
+    attr_reader :response_body
+
+    # Initialize a new Error
+    #
+    # @param message [String] Error message
+    # @param status [Integer, nil] HTTP status code
+    # @param response_body [Hash, nil] Parsed response body
+    def initialize(message = nil, status: nil, response_body: nil)
+      @status = status
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  # Raised when the API key is missing or invalid
+  class ConfigurationError < Error; end
+
+  # Base class for HTTP errors returned by the API
+  class APIError < Error; end
+
+  # Raised when authentication fails (401)
+  class AuthenticationError < APIError; end
+
+  # Raised when the request is forbidden (403)
+  class ForbiddenError < APIError; end
+
+  # Raised when a resource is not found (404)
+  class NotFoundError < APIError; end
+
+  # Raised when the request is invalid (400)
+  class BadRequestError < APIError; end
+
+  # Raised when validation fails (422)
+  class UnprocessableEntityError < APIError; end
+
+  # Raised when rate limit is exceeded (429)
+  class RateLimitError < APIError
+    # @return [Integer, nil] Seconds until rate limit resets
+    attr_reader :retry_after
+
+    def initialize(message = nil, status: nil, response_body: nil, retry_after: nil)
+      @retry_after = retry_after
+      super(message, status: status, response_body: response_body)
+    end
+  end
+
+  # Raised when there's a server error (500, 502, 503, 504)
+  class ServerError < APIError; end
+
+  # Raised when there's a network/connection error
+  class ConnectionError < Error; end
+
+  # Raised when a request times out
+  class TimeoutError < ConnectionError; end
+
+  # Maps HTTP status codes to error classes
+  HTTP_STATUS_ERRORS = {
+    400 => BadRequestError,
+    401 => AuthenticationError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    422 => UnprocessableEntityError,
+    429 => RateLimitError,
+    500 => ServerError,
+    502 => ServerError,
+    503 => ServerError,
+    504 => ServerError
+  }.freeze
+end

data/lib/data_nexus/resources/member_consents.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module DataNexus
+  module Resources
+    # Resource for managing member consents
+    #
+    # Provides methods for creating, finding, updating, and deleting
+    # consents for a specific member.
+    #
+    # @example Create a consent
+    #   client.programs("uuid").members("member-id").consents.create(
+    #     consent: {
+    #       category: "sms",
+    #       member_response: true,
+    #       consent_details: { sms_phone_number: "+15558675309" }
+    #     }
+    #   )
+    #
+    # @example Find a consent
+    #   consent = client.programs("uuid").members("member-id").consents.find(123)
+    #
+    # @example Update a consent
+    #   client.programs("uuid").members("member-id").consents.update(123,
+    #     consent: { member_response: false }
+    #   )
+    #
+    # @example Delete a consent
+    #   client.programs("uuid").members("member-id").consents.delete(123)
+    #
+    class MemberConsents
+      # @return [Connection] The HTTP connection
+      attr_reader :connection
+
+      # @return [String] The member ID
+      attr_reader :member_id
+
+      # @return [String] The program UUID
+      attr_reader :program_id
+
+      # Initialize a new MemberConsents resource
+      #
+      # @param connection [Connection] The HTTP connection
+      # @param member_id [String] The member ID
+      # @param program_id [String] The program UUID
+      def initialize(connection, member_id, program_id)
+        @connection = connection
+        @member_id = member_id
+        @program_id = program_id
+      end
+
+      # Create a new consent for the member
+      #
+      # @param consent [Hash] The consent attributes
+      # @option consent [String] :category The consent category (required)
+      # @option consent [Hash] :consent_details Additional consent details (required, can be empty)
+      # @option consent [String] :consented_at The datetime of consent (optional)
+      # @option consent [Boolean] :member_response Whether member agreed (optional, default: false)
+      # @return [Hash] Response containing :data with the created consent
+      #
+      # @example
+      #   response = client.programs("uuid").members("member-id").consents.create(
+      #     consent: {
+      #       category: "sms",
+      #       member_response: true,
+      #       consent_details: { sms_phone_number: "+15558675309" }
+      #     }
+      #   )
+      #   created_consent = response[:data]
+      def create(consent:)
+        consent_with_program = consent.merge(program_id: program_id)
+        body = { consent: consent_with_program }
+        connection.post(base_path, body)
+      end
+
+      # Find a specific consent by ID
+      #
+      # @param consent_id [Integer, String] The consent ID
+      # @return [Hash] The consent data
+      #
+      # @example
+      #   consent = client.programs("uuid").members("member-id").consents.find(123)
+      #   puts consent[:category]
+      def find(consent_id)
+        response = connection.get("#{base_path}/#{consent_id}")
+        response[:data]
+      end
+
+      # Update a consent's attributes
+      #
+      # @param consent_id [Integer, String] The consent ID
+      # @param consent [Hash] The consent attributes to update
+      # @return [Hash] Response containing :data with the updated consent
+      #
+      # @example
+      #   response = client.programs("uuid").members("member-id").consents.update(123,
+      #     consent: { member_response: false }
+      #   )
+      #   updated_consent = response[:data]
+      def update(consent_id, consent:)
+        body = { consent: consent }
+        connection.patch("#{base_path}/#{consent_id}", body)
+      end
+
+      # Delete a consent
+      #
+      # @param consent_id [Integer, String] The consent ID
+      # @return [Hash] Empty hash on success (204 No Content)
+      #
+      # @example
+      #   client.programs("uuid").members("member-id").consents.delete(123)
+      def delete(consent_id)
+        connection.delete("#{base_path}/#{consent_id}")
+      end
+
+      private
+
+      # Base path for member consents endpoints
+      #
+      # @return [String]
+      def base_path
+        "/api/members/#{member_id}/consents"
+      end
+    end
+  end
+end

data/lib/data_nexus/resources/member_enrollments.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module DataNexus
+  module Resources
+    # Resource for managing member enrollments
+    #
+    # Provides methods for creating, finding, updating, and deleting
+    # enrollments for a specific member.
+    #
+    # @example Create an enrollment
+    #   client.programs("program-uuid").members("member-id").enrollments.create(
+    #     enrollment: {
+    #       enrolled_at: "2024-01-01T00:00:00Z",
+    #       expires_at: "2025-01-01T00:00:00Z"
+    #     }
+    #   )
+    #
+    # @example Find an enrollment
+    #   enrollment = client.programs("program-uuid").members("member-id").enrollments.find(123)
+    #
+    # @example Update an enrollment
+    #   client.programs("program-uuid").members("member-id").enrollments.update(123,
+    #     enrollment: { expires_at: "2026-01-01T00:00:00Z" }
+    #   )
+    #
+    # @example Delete an enrollment
+    #   client.programs("program-uuid").members("member-id").enrollments.delete(123)
+    #
+    class MemberEnrollments
+      # @return [Connection] The HTTP connection
+      attr_reader :connection
+
+      # @return [String] The member ID
+      attr_reader :member_id
+
+      # @return [String] The program UUID
+      attr_reader :program_id
+
+      # Initialize a new MemberEnrollments resource
+      #
+      # @param connection [Connection] The HTTP connection
+      # @param member_id [String] The member ID
+      # @param program_id [String] The program UUID
+      def initialize(connection, member_id, program_id)
+        @connection = connection
+        @member_id = member_id
+        @program_id = program_id
+      end
+
+      # Create a new enrollment for the member
+      #
+      # @param enrollment [Hash] The enrollment attributes
+      # @option enrollment [String] :enrolled_at The datetime of enrollment (required)
+      # @option enrollment [String] :expires_at The datetime when enrollment expires (optional)
+      # @return [Hash] Response containing :data with the created enrollment
+      #
+      # @note The program_id is automatically injected from the resource chain
+      #
+      # @example
+      #   response = client.programs("program-uuid").members("member-id").enrollments.create(
+      #     enrollment: {
+      #       enrolled_at: "2024-01-01T00:00:00Z"
+      #     }
+      #   )
+      #   created_enrollment = response[:data]
+      def create(enrollment:)
+        enrollment_with_program = enrollment.merge(program_id: program_id)
+        body = { enrollment: enrollment_with_program }
+        connection.post(base_path, body)
+      end
+
+      # Find a specific enrollment by ID
+      #
+      # @param enrollment_id [Integer, String] The enrollment ID
+      # @return [Hash] The enrollment data
+      #
+      # @example
+      #   enrollment = client.programs("program-uuid").members("member-id").enrollments.find(123)
+      #   puts enrollment[:program_id]
+      def find(enrollment_id)
+        response = connection.get("#{base_path}/#{enrollment_id}")
+        response[:data]
+      end
+
+      # Update an enrollment's attributes
+      #
+      # @param enrollment_id [Integer, String] The enrollment ID
+      # @param enrollment [Hash] The enrollment attributes to update
+      # @return [Hash] Response containing :data with the updated enrollment
+      #
+      # @example
+      #   response = client.programs("program-uuid").members("member-id").enrollments.update(123,
+      #     enrollment: { expires_at: "2026-01-01T00:00:00Z" }
+      #   )
+      #   updated_enrollment = response[:data]
+      def update(enrollment_id, enrollment:)
+        body = { enrollment: enrollment }
+        connection.patch("#{base_path}/#{enrollment_id}", body)
+      end
+
+      # Delete an enrollment
+      #
+      # @param enrollment_id [Integer, String] The enrollment ID
+      # @return [Hash] Empty hash on success (204 No Content)
+      #
+      # @example
+      #   client.programs("program-uuid").members("member-id").enrollments.delete(123)
+      def delete(enrollment_id)
+        connection.delete("#{base_path}/#{enrollment_id}")
+      end
+
+      private
+
+      # Base path for member enrollments endpoints
+      #
+      # @return [String]
+      def base_path
+        "/api/members/#{member_id}/enrollments"
+      end
+    end
+  end
+end

data/lib/data_nexus/resources/members.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module DataNexus
+  module Resources
+    # Resource for managing members at the top level
+    #
+    # Provides methods for listing, finding, and updating members
+    # without requiring a program scope.
+    #
+    # @example List members with filters
+    #   client.members.list(
+    #     first_name: "george",
+    #     born_on: "1976-07-04"
+    #   )
+    #
+    # @example Paginate through members
+    #   collection = client.members.list(first: 50)
+    #   collection.each_page { |page| process(page.data) }
+    #
+    # @example Find a specific member
+    #   member = client.members.find("member-id")
+    #
+    class Members
+      # @return [Connection] The HTTP connection
+      attr_reader :connection
+
+      # Initialize a new Members resource
+      #
+      # @param connection [Connection] The HTTP connection
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # List members with optional filters
+      #
+      # @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
+      # @param born_on [String, nil] Filter by date of birth (YYYY-MM-DD)
+      # @param first_name [String, nil] Filter by first name
+      # @param last_name [String, nil] Filter by last name
+      # @param program_id [String, nil] Filter by program UUID (members eligible for program)
+      # @param updated_since [String, nil] Filter by update time (ISO 8601 datetime)
+      #
+      # @return [Collection] Paginated collection of members
+      #
+      # @example Basic listing
+      #   collection = client.members.list
+      #   collection.data.each { |m| puts m[:first_name] }
+      #
+      # @example With filters
+      #   collection = client.members.list(
+      #     born_on: "1976-07-04",
+      #     first_name: "george"
+      #   )
+      #
+      # @example With pagination
+      #   collection = client.members.list(first: 50, after: "cursor")
+      #
+      # @example Filter by program eligibility
+      #   collection = client.members.list(program_id: "uuid")
+      #
+      # @example Filter by update time
+      #   collection = client.members.list(updated_since: "2024-01-01T00:00:00Z")
+      def list(**params)
+        allowed_params = %i[
+          after before first last
+          born_on first_name last_name
+          program_id updated_since
+        ]
+
+        query_params = params.slice(*allowed_params).compact
+        response = connection.get(base_path, query_params)
+        Collection.new(response, resource: self, params: query_params)
+      end
+
+      # Find a specific member by ID
+      #
+      # @param member_id [String] The member ID
+      # @return [Hash] The member data
+      #
+      # @example
+      #   member = client.members.find("member-id")
+      #   puts member[:first_name]
+      def find(member_id)
+        response = connection.get("#{base_path}/#{member_id}")
+        response[:data]
+      end
+
+      # Update a member's attributes
+      #
+      # @param member_id [String] The member ID
+      # @param member [Hash] The member attributes to update
+      # @return [Hash] Response containing :data with the updated member
+      #
+      # @example
+      #   response = client.members.update("member-id",
+      #     member: { phone_number: "+15551234567" }
+      #   )
+      #   updated_member = response[:data]
+      def update(member_id, member:)
+        body = { member: member }
+        connection.patch("#{base_path}/#{member_id}", body)
+      end
+
+      private
+
+      # Base path for members endpoints
+      #
+      # @return [String]
+      def base_path
+        '/api/members'
+      end
+    end
+  end
+end