vitable-connect 0.6.0 → 1.0.0

data/lib/VitableConnect/groups/client.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    class Client
+      # @param client [VitableConnect::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Returns a paginated list of groups belonging to the authenticated organization.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [Integer, nil] :limit
+      # @option params [Integer, nil] :page
+      #
+      # @example
+      #   client.groups.list(
+      #     limit: 20,
+      #     page: 1
+      #   )
+      #
+      # @return [VitableConnect::Types::GroupListResponse]
+      def list(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        query_params = {}
+        query_params["limit"] = params[:limit] if params.key?(:limit)
+        query_params["page"] = params[:page] if params.key?(:page)
+
+        VitableConnect::Internal::OffsetItemIterator.new(
+          initial_page: query_params["page"],
+          item_field: :data,
+          has_next_field: nil,
+          step: false
+        ) do |next_page|
+          query_params["page"] = next_page
+          request = VitableConnect::Internal::JSON::Request.new(
+            base_url: request_options[:base_url],
+            method: "GET",
+            path: "v1/groups",
+            query: query_params,
+            request_options: request_options
+          )
+          begin
+            response = @client.send(request)
+          rescue Net::HTTPRequestTimeout
+            raise VitableConnect::Errors::TimeoutError
+          end
+          code = response.code.to_i
+          if code.between?(200, 299)
+            parsed_response = VitableConnect::Types::GroupListResponse.load(response.body)
+            [parsed_response, response]
+          else
+            error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+            raise error_class.new(response.body, code: code)
+          end
+        end
+      end
+
+      # Creates a new group scoped to the authenticated organization.
+      #
+      # @param request_options [Hash]
+      # @param params [VitableConnect::Groups::Types::CreateGroupRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @example
+      #   client.groups.create(
+      #     name: "Tier 1",
+      #     external_reference_id: "mol_seg_001"
+      #   )
+      #
+      # @return [VitableConnect::Types::GroupResponse]
+      def create(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        request = VitableConnect::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "v1/groups",
+          body: VitableConnect::Groups::Types::CreateGroupRequest.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise VitableConnect::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          VitableConnect::Types::GroupResponse.load(response.body)
+        else
+          error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Retrieves a single group by its prefixed ID. Returns 404 if the group does not belong to the authenticated
+      # organization.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [VitableConnect::Types::GroupID] :group_id
+      #
+      # @example
+      #   client.groups.get(group_id: "grp_abc123def456")
+      #
+      # @return [VitableConnect::Types::GroupResponse]
+      def get(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        request = VitableConnect::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "v1/groups/#{URI.encode_uri_component(params[:group_id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise VitableConnect::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          VitableConnect::Types::GroupResponse.load(response.body)
+        else
+          error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Partially updates a group's name or external reference ID. Returns 404 if the group does not belong to the
+      # authenticated organization.
+      #
+      # @param request_options [Hash]
+      # @param params [VitableConnect::Groups::Types::PatchedUpdateGroupRequest]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [VitableConnect::Types::GroupID] :group_id
+      #
+      # @example
+      #   client.groups.update(
+      #     group_id: "grp_abc123def456",
+      #     name: "Tier 1 (renamed)",
+      #     external_reference_id: "mol_seg_001_v2"
+      #   )
+      #
+      # @return [VitableConnect::Types::GroupResponse]
+      def update(request_options: {}, **params)
+        params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+        request_data = VitableConnect::Groups::Types::PatchedUpdateGroupRequest.new(params).to_h
+        non_body_param_names = %w[group_id]
+        body = request_data.except(*non_body_param_names)
+
+        request = VitableConnect::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "PATCH",
+          path: "v1/groups/#{URI.encode_uri_component(params[:group_id].to_s)}",
+          body: body,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise VitableConnect::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          VitableConnect::Types::GroupResponse.load(response.body)
+        else
+          error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # @return [VitableConnect::Members::Client]
+      def members
+        @members ||= VitableConnect::Groups::Members::Client.new(client: @client)
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/members/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Members
+      class Client
+        # @param client [VitableConnect::Internal::Http::RawClient]
+        #
+        # @return [void]
+        def initialize(client:)
+          @client = client
+        end
+
+        # @return [VitableConnect::Sync::Client]
+        def sync
+          @sync ||= VitableConnect::Groups::Members::Sync::Client.new(client: @client)
+        end
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/members/sync/client.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Members
+      module Sync
+        class Client
+          # @param client [VitableConnect::Internal::Http::RawClient]
+          #
+          # @return [void]
+          def initialize(client:)
+            @client = client
+          end
+
+          # Submits a member sync payload for the specified group. Members in the payload will be queued for processing
+          # asynchronously. Returns HTTP 202 with the batch ID and acceptance timestamp.
+          #
+          # @param request_options [Hash]
+          # @param params [VitableConnect::Groups::Members::Sync::Types::GroupMemberSyncRequest]
+          # @option request_options [String] :base_url
+          # @option request_options [Hash{String => Object}] :additional_headers
+          # @option request_options [Hash{String => Object}] :additional_query_parameters
+          # @option request_options [Hash{String => Object}] :additional_body_parameters
+          # @option request_options [Integer] :timeout_in_seconds
+          # @option params [VitableConnect::Types::GroupID] :group_id
+          #
+          # @example
+          #   client.groups.members.sync.submit(
+          #     group_id: "grp_abc123def456",
+          #     members: [{
+          #       reference_id: "EMP-001",
+          #       first_name: "Jane",
+          #       last_name: "Doe",
+          #       date_of_birth: "1990-05-15",
+          #       phone: "4155550100",
+          #       plan_id: "pln_abc123def456",
+          #       address: {
+          #         address_line1: "123 Main Street",
+          #         address_line2: "Apt 4B",
+          #         city: "San Francisco",
+          #         state: "CA",
+          #         zipcode: "94102"
+          #       },
+          #       email: "jane.doe@acme.com"
+          #     }]
+          #   )
+          #
+          # @return [VitableConnect::Types::GroupMemberSyncDetailResponse]
+          def submit(request_options: {}, **params)
+            params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+            request_data = VitableConnect::Groups::Members::Sync::Types::GroupMemberSyncRequest.new(params).to_h
+            non_body_param_names = %w[group_id]
+            body = request_data.except(*non_body_param_names)
+
+            request = VitableConnect::Internal::JSON::Request.new(
+              base_url: request_options[:base_url],
+              method: "POST",
+              path: "v1/groups/#{URI.encode_uri_component(params[:group_id].to_s)}/members/sync",
+              body: body,
+              request_options: request_options
+            )
+            begin
+              response = @client.send(request)
+            rescue Net::HTTPRequestTimeout
+              raise VitableConnect::Errors::TimeoutError
+            end
+            code = response.code.to_i
+            if code.between?(200, 299)
+              VitableConnect::Types::GroupMemberSyncDetailResponse.load(response.body)
+            else
+              error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+              raise error_class.new(response.body, code: code)
+            end
+          end
+
+          # Retrieves a previously-submitted group member sync request by its `grpmsr_` ID. Returns the acceptance
+          # timestamp, completion timestamp (if processing has finished), and the per-member `results` once available.
+          # While processing is in flight, `completed_at` and `results` are `null`.
+          #
+          # @param request_options [Hash]
+          # @param params [Hash]
+          # @option request_options [String] :base_url
+          # @option request_options [Hash{String => Object}] :additional_headers
+          # @option request_options [Hash{String => Object}] :additional_query_parameters
+          # @option request_options [Hash{String => Object}] :additional_body_parameters
+          # @option request_options [Integer] :timeout_in_seconds
+          # @option params [VitableConnect::Types::GroupID] :group_id
+          # @option params [VitableConnect::Types::RequestID] :request_id
+          #
+          # @example
+          #   client.groups.members.sync.get(
+          #     group_id: "grp_abc123def456",
+          #     request_id: "request_id"
+          #   )
+          #
+          # @return [VitableConnect::Types::GroupMemberSyncRequestDetailResponse]
+          def get(request_options: {}, **params)
+            params = VitableConnect::Internal::Types::Utils.normalize_keys(params)
+            request = VitableConnect::Internal::JSON::Request.new(
+              base_url: request_options[:base_url],
+              method: "GET",
+              path: "v1/groups/#{URI.encode_uri_component(params[:group_id].to_s)}/members/sync/#{URI.encode_uri_component(params[:request_id].to_s)}",
+              request_options: request_options
+            )
+            begin
+              response = @client.send(request)
+            rescue Net::HTTPRequestTimeout
+              raise VitableConnect::Errors::TimeoutError
+            end
+            code = response.code.to_i
+            if code.between?(200, 299)
+              VitableConnect::Types::GroupMemberSyncRequestDetailResponse.load(response.body)
+            else
+              error_class = VitableConnect::Errors::ResponseError.subclass_for_code(code)
+              raise error_class.new(response.body, code: code)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/members/sync/types/get_sync_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Members
+      module Sync
+        module Types
+          class GetSyncRequest < Internal::Types::Model
+            field :group_id, -> { String }, optional: false, nullable: false
+
+            field :request_id, -> { String }, optional: false, nullable: false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/members/sync/types/group_member_sync_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Members
+      module Sync
+        module Types
+          class GroupMemberSyncRequest < Internal::Types::Model
+            field :group_id, -> { String }, optional: false, nullable: false
+
+            field :members, -> { Internal::Types::Array[VitableConnect::Types::GroupMemberSyncMemberRequest] }, optional: false, nullable: false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/types/create_group_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Types
+      class CreateGroupRequest < Internal::Types::Model
+        field :name, -> { String }, optional: false, nullable: false
+
+        field :external_reference_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/types/get_groups_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Types
+      class GetGroupsRequest < Internal::Types::Model
+        field :group_id, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/types/list_groups_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Types
+      class ListGroupsRequest < Internal::Types::Model
+        field :limit, -> { Integer }, optional: true, nullable: false
+
+        field :page, -> { Integer }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/groups/types/patched_update_group_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Groups
+    module Types
+      class PatchedUpdateGroupRequest < Internal::Types::Model
+        field :group_id, -> { String }, optional: false, nullable: false
+
+        field :name, -> { String }, optional: true, nullable: false
+
+        field :external_reference_id, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/VitableConnect/internal/errors/constraint_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Internal
+    module Errors
+      class ConstraintError < StandardError
+      end
+    end
+  end
+end

data/lib/VitableConnect/internal/errors/type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Internal
+    module Errors
+      class TypeError < StandardError
+      end
+    end
+  end
+end

data/lib/VitableConnect/internal/http/base_request.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module VitableConnect
+  module Internal
+    module Http
+      # @api private
+      class BaseRequest
+        attr_reader :base_url, :path, :method, :headers, :query, :request_options
+
+        # @param base_url [String] The base URL for the request
+        # @param path [String] The path for the request
+        # @param method [String] The HTTP method for the request (:get, :post, etc.)
+        # @param headers [Hash] Additional headers for the request (optional)
+        # @param query [Hash] Query parameters for the request (optional)
+        # @param request_options [VitableConnect::RequestOptions, Hash{Symbol=>Object}, nil]
+        def initialize(base_url:, path:, method:, headers: {}, query: {}, request_options: {})
+          @base_url = base_url
+          @path = path
+          @method = method
+          @headers = headers
+          @query = query
+          @request_options = request_options
+        end
+
+        # @return [Hash] The query parameters merged with additional query parameters from request options.
+        def encode_query
+          additional_query = @request_options&.dig(:additional_query_parameters) || @request_options&.dig("additional_query_parameters") || {}
+          @query.merge(additional_query)
+        end
+
+        # Child classes should implement:
+        # - encode_headers: Returns the encoded HTTP request headers.
+        # - encode_body: Returns the encoded HTTP request body.
+
+        private
+
+        # Merges additional_headers from request_options into sdk_headers, filtering out
+        # any keys that collide with SDK-set or client-protected headers (case-insensitive).
+        # @param sdk_headers [Hash] Headers set by the SDK for this request type.
+        # @param protected_keys [Array<String>] Additional header keys that must not be overridden.
+        # @return [Hash] The merged headers.
+        def merge_additional_headers(sdk_headers, protected_keys: [])
+          additional_headers = @request_options&.dig(:additional_headers) || @request_options&.dig("additional_headers") || {}
+          all_protected = (sdk_headers.keys + protected_keys).to_set { |k| k.to_s.downcase }
+          filtered = additional_headers.reject { |key, _| all_protected.include?(key.to_s.downcase) }
+          sdk_headers.merge(filtered)
+        end
+      end
+    end
+  end
+end