apimatic_core 0.3.14 → 0.3.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00e9fe70fd66ace8622a12149e08ae651839bf8c3ab555fd88b48075b63fa3f3
-  data.tar.gz: 47b65583f2a0f4badb201965ea172c7683bdba5074e30d737ca2f35a04605b7f
+  metadata.gz: 6ecc4f4597c759974681f7105595172534b8ae7864654711e4f7ed04db6fa518
+  data.tar.gz: d9d62ba896f853026f2d52f242241048a91ae5e49a1b5906b2c1ee78ee3559e3
 SHA512:
-  metadata.gz: 19bf7dbb3489e33e7d9aa84f97fc28a98e9360e9c0a631750844041c46348c9fed64e3060dd33c381fd5eedcc53386a142970c5a821c0d9119f7fbe250d7d93f
-  data.tar.gz: 6c93a64bb2fb27f72688fea390a0f97f47729e945d75bf6c2df19f6708f13bd9a832cc4785129edb4310fce6f995012ecc8d80724fc1022f37b80055900f7384
+  metadata.gz: 3df51d480ddfc862d60c5452f6b15a71d091ebe64db5e5f86ef885ee402f9dffabee2a644a94c33a6572ce55383b04cf8720b4d70f9d87fece77da65741c9626
+  data.tar.gz: 7eda9192920928a35a9d9e09bf2937348972aa8bcdaf37fdd153da1abf357b9c259cee74e59c17e1845cbb2fb57cbcd18997dd5e5c381422d0e74ac692249368

data/README.md

@@ -62,22 +62,32 @@ gem 'apimatic_core'
 | [`HttpResponseFactory`](lib/apimatic-core/factories/http_response_factory.rb) | Factory class to create an HTTP Response |
 
 ## HTTP
-| Name                                                                                            | Description                                              |
-|-------------------------------------------------------------------------------------------------|----------------------------------------------------------|
-| [`HttpClientConfiguration`](lib/apimatic-core/http/configurations/http_client_configuration.rb) | Class used for configuring SDK by a user                 |
-| [`HttpRequest`](lib/apimatic-core/http/request/http_request.rb)                                 | Class which contains information about the HTTP Request  |
-| [`ApiResponse`](lib/apimatic-core/http/response/api_response.rb)                                | Wrapper class for Api Response                           |
-| [`HttpResponse`](lib/apimatic-core/http/response/http_response.rb)                              | Class which contains information about the HTTP Response |
+| Name                                                                                            | Description                                                                                                                                                      |
+|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`HttpClientConfiguration`](lib/apimatic-core/http/configurations/http_client_configuration.rb) | Class used for configuring SDK by a user                                                                                                                         |
+| [`HttpRequest`](lib/apimatic-core/http/request/http_request.rb)                                 | Class which contains information about the HTTP Request                                                                                                          |
+| [`ApiResponse`](lib/apimatic-core/http/response/api_response.rb)                                | Wrapper class for Api Response                                                                                                                                   |
+| [`HttpResponse`](lib/apimatic-core/http/response/http_response.rb)                              | Class which contains information about the HTTP Response                                                                                                         |
+| [`HttpCallContext`](lib/apimatic-core/http/http_call_context.rb)                                | This class captures the HTTP request and response lifecycle during an API call and is used with clients or controllers that support pre- and post-request hooks. |
 
 ## Logger
-| Name                                                              | Description                                |
-|-------------------------------------------------------------------|--------------------------------------------|
-| [`SdkLogger`](lib/apimatic-core/logger/sdk_logger.rb)   | A class responsible for logging request and response of an api call|
-| [`NilSdkLogger`](lib/apimatic-core/logger/nil_sdk_logger.rb)   | A class responsible for no logging|
-| [`ConsoleLogger`](lib/apimatic-core/logger/default_logger.rb)   | Represents default implementation of logger interface|
-| [`ApiLoggingConfiguration`](lib/apimatic-core/logger/api_logging_configuration.rb)   | Represents logging configuration|
-| [`ApiRequestLoggingConfiguration`](lib/apimatic-core/logger/api_logging_configuration.rb)   | Represents request logging configuration.|
-| [`ApiResponseLoggingConfiguration`](lib/apimatic-core/logger/api_logging_configuration.rb)   | Represents response logging configuration.|
+| Name                                                                                       | Description                                                         |
+|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| [`SdkLogger`](lib/apimatic-core/logger/sdk_logger.rb)                                      | A class responsible for logging request and response of an api call |
+| [`NilSdkLogger`](lib/apimatic-core/logger/nil_sdk_logger.rb)                               | A class responsible for no logging                                  |
+| [`ConsoleLogger`](lib/apimatic-core/logger/default_logger.rb)                              | Represents default implementation of logger interface               |
+| [`ApiLoggingConfiguration`](lib/apimatic-core/logger/api_logging_configuration.rb)         | Represents logging configuration                                    |
+| [`ApiRequestLoggingConfiguration`](lib/apimatic-core/logger/api_logging_configuration.rb)  | Represents request logging configuration.                           |
+| [`ApiResponseLoggingConfiguration`](lib/apimatic-core/logger/api_logging_configuration.rb) | Represents response logging configuration.                          |
+
+## Pagination
+| Name                                                                               | Description                                                                                                                                      |
+|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`CursorPagination`](lib/apimatic-core/pagination/strategies/cursor_pagination.rb) | Cursor-based pagination strategy that handles extraction and injection of cursor values for seamless traversal across paged API responses.       |
+| [`LinkPagination`](lib/apimatic-core/pagination/strategies/link_pagination.rb)     | Extracts the next page link from API responses via a JSON pointer and updates the request builder with corresponding query parameters.           |
+| [`OffsetPagination`](lib/apimatic-core/pagination/strategies/offset_pagination.rb) | Offset-based pagination using a configurable JSON pointer to update and track offset values in the request builder across responses.             |
+| [`PagePagination`](lib/apimatic-core/pagination/strategies/page_pagination.rb)     | Page-based pagination strategy that updates the request builder with page numbers using a JSON pointer and wraps each response with metadata.    |
+| [`PaginatedData`](lib/apimatic-core/pagination/paginated_data.rb)                  | Iterator for paginated API responses supporting multiple strategies, item/page iteration, and access to the latest response and request builder. |
 
 ## Types
 | Name                                                                            | Description                                                                   |
@@ -94,14 +104,19 @@ gem 'apimatic_core'
 | [`XmlAttributes`](lib/apimatic-core/types/xml_attributes.rb)                    | A class to represent information about an XML Parameter passed in an endpoint |
 
 ## Utilities
-| Name                                                                   | Description                                                                           |
-|------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
-| [`ApiHelper`](lib/apimatic-core/utilities/api_helper.rb)               | A Helper Class with various functions associated with making an API Call              |
-| [`AuthHelper`](lib/apimatic-core/utilities/auth_helper.rb)             | A Helper Class with various functions associated with authentication in API Calls     |
-| [`UnionTypeHelper`](lib/apimatic-core/utilities/union_type_helper.rb)  | A Helper Class with various functions associated with Union type in API Calls         |
-| [`ComparisonHelper`](lib/apimatic-core/utilities/comparison_helper.rb) | A Helper Class used for the comparison of expected and actual API response            |
-| [`FileHelper`](lib/apimatic-core/utilities/file_helper.rb)             | A Helper Class for files                                                              |
-| [`XmlHelper`](lib/apimatic-core/utilities/xml_helper.rb )              | A Helper class that holds utility methods for xml serialization and deserialization.  |
+| Name                                                                       | Description                                                                                                            |
+|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| [`ApiHelper`](lib/apimatic-core/utilities/api_helper.rb)                   | A Helper Class with various functions associated with making an API Call                                               |
+| [`AuthHelper`](lib/apimatic-core/utilities/auth_helper.rb)                 | A Helper Class with various functions associated with authentication in API Calls                                      |
+| [`UnionTypeHelper`](lib/apimatic-core/utilities/union_type_helper.rb)      | A Helper Class with various functions associated with Union type in API Calls                                          |
+| [`ComparisonHelper`](lib/apimatic-core/utilities/comparison_helper.rb)     | A Helper Class used for the comparison of expected and actual API response                                             |
+| [`FileHelper`](lib/apimatic-core/utilities/file_helper.rb)                 | A Helper Class for files                                                                                               |
+| [`XmlHelper`](lib/apimatic-core/utilities/xml_helper.rb )                  | A Helper class that holds utility methods for xml serialization and deserialization.                                   |
+| [`DateTimeHelper`](lib/apimatic-core/utilities/date_time_helper.rb )       | Utility methods for date-time format conversions.                                                                      |
+| [`DeepCloneUtils`](lib/apimatic-core/utilities/deep_clone_utils.rb )       | Utility methods for deep cloning arrays, hashes, and objects.                                                          |
+| [`JsonPointerHelper`](lib/apimatic-core/utilities/json_pointer_helper.rb ) | Utility methods for getting and setting JSON pointer values in hashes.                                                 |
+| [`JsonPointer`](lib/apimatic-core/utilities/json_pointer.rb )              | Enables querying, updating, and deleting values in nested Ruby Hashes and Arrays using JSON Pointer syntax (RFC 6901). |
+| [`LoggerHelper`](lib/apimatic-core/utilities/logger_helper.rb )            | Utility methods for logging.                                                                                           |
 
 ## Links
 * [apimatic_core_interfaces](https://rubygems.org/gems/apimatic_core_interfaces)

data/lib/apimatic-core/api_call.rb

@@ -1,11 +1,7 @@
 module CoreLibrary
   # This class is responsible for executing an API call using HttpClient, RequestBuilder and ResponseHandler objects.
   class ApiCall
-    # Creates a new builder instance of the API call with pre-configured global and logging configurations.
-    # @return [ApiCall] The instance of ApiCall object.
-    def new_builder
-      ApiCall.new(@global_configuration)
-    end
+    attr_reader :request_builder, :pagination_strategy_list, :global_configuration
 
     # Initializes a new instance of ApiCall.
     # @param [GlobalConfiguration] global_configuration An instance of GlobalConfiguration.
@@ -15,6 +11,7 @@ module CoreLibrary
       @response_handler = ResponseHandler.new
       @endpoint_context = {}
       initialize_api_logger(@global_configuration.client_configuration.logging_configuration)
+      @pagination_strategy_list = nil
     end
 
     # The setter for the request builder to be used for building the request of an API call.
@@ -42,6 +39,15 @@ module CoreLibrary
       self
     end
 
+    # Sets the pagination strategies for this instance.
+    #
+    # @param pagination_strategies [Array<Object>] A variable number of pagination strategy objects.
+    # @return [self] Returns the current instance for method chaining.
+    def pagination_strategies(*pagination_strategies)
+      @pagination_strategy_list = pagination_strategies
+      self
+    end
+
     # Executes the API call using provided HTTP client, request builder and response handler objects.
     # @return The deserialized endpoint response.
     def execute
@@ -78,6 +84,17 @@ module CoreLibrary
       end
     end
 
+    # Invokes the given page iterable creator with a PaginatedData instance.
+    #
+    # @param page_iterable_creator [Proc] A callable that accepts a PaginatedData instance
+    #   and returns an iterable (e.g., Enumerator) over pages of results.
+    # @param paginated_items_converter [Proc] A callable used to convert paginated items.
+    #
+    # @return [Object] The result of calling page_iterable_creator with the PaginatedData.
+    def paginate(page_iterable_creator, paginated_items_converter)
+      page_iterable_creator.call(PaginatedData.new(self, paginated_items_converter))
+    end
+
     # Registers request and response with the provided http_callback
     # @param [Callable] callable The callable to be called for registering into the HttpCallback instance.
     def update_http_callback(callable)
@@ -91,5 +108,37 @@ module CoreLibrary
                   SdkLogger.new(logging_config)
                 end
     end
+
+    # Creates a deep clone of the ApiCall instance with optional overrides.
+    #
+    # This method is useful for duplicating an API call while changing select parts like
+    # the request builder or pagination strategies.
+    #
+    # @param global_configuration [GlobalConfiguration, nil] Optional replacement global configuration.
+    # @param request_builder [RequestBuilder, nil] Optional replacement request builder.
+    #
+    # @return [ApiCall] A new instance with copied internal state and any applied overrides.
+    def clone_with(global_configuration: nil, request_builder: nil)
+      clone = ApiCall.new(global_configuration || @global_configuration)
+
+      clone.request(request_builder || @request_builder.clone_with)
+      clone.response(@response_handler)
+      clone.set_endpoint_context(DeepCloneUtils.deep_copy(@endpoint_context))
+      clone.pagination_strategies(*pagination_strategy_list) if pagination_strategy_list
+
+      clone
+    end
+
+    protected
+
+    # Sets the entire endpoint context hash to be used in building the API request.
+    #
+    # This replaces any previously set context values with the provided hash.
+    # It is typically used when cloning `ApiCall` instance.
+    #
+    # @param [Hash{String=>Object}] endpoint_context The full endpoint context to assign.
+    def set_endpoint_context(endpoint_context)
+      @endpoint_context = endpoint_context
+    end
   end
 end

data/lib/apimatic-core/configurations/global_configuration.rb

@@ -136,5 +136,21 @@ module CoreLibrary
       end
       @global_headers['user-agent'] = user_agent unless user_agent.nil?
     end
+
+    def clone_with(client_configuration: nil)
+      clone = GlobalConfiguration.new(
+        client_configuration: client_configuration || DeepCloneUtils.deep_copy(@client_configuration)
+      )
+
+      # Copy internal state
+      clone.global_errors(DeepCloneUtils.deep_copy(@global_errors))
+      clone.global_headers(DeepCloneUtils.deep_copy(@global_headers))
+      clone.additional_headers(DeepCloneUtils.deep_copy(@additional_headers))
+      clone.auth_managers(DeepCloneUtils.deep_copy(@auth_managers))
+      clone.base_uri_executor(DeepCloneUtils.deep_copy(@base_uri_executor))
+      clone.symbolize_hash(@symbolize_hash)
+
+      clone
+    end
   end
 end

data/lib/apimatic-core/http/configurations/http_client_configuration.rb

@@ -43,5 +43,23 @@ module CoreLibrary
     def set_http_client(http_client)
       @http_client = http_client
     end
+
+    def clone_with(http_callback: nil)
+      HttpClientConfiguration.new(
+        connection: DeepCloneUtils.deep_copy(@connection),
+        adapter: DeepCloneUtils.deep_copy(@adapter),
+        timeout: @timeout,
+        max_retries: @max_retries,
+        retry_interval: @retry_interval,
+        backoff_factor: @backoff_factor,
+        retry_statuses: DeepCloneUtils.deep_copy(@retry_statuses),
+        retry_methods: DeepCloneUtils.deep_copy(@retry_methods),
+        cache: @cache,
+        verify: @verify,
+        http_callback: http_callback || DeepCloneUtils.deep_copy(@http_callback),
+        http_client: DeepCloneUtils.deep_copy(@http_client),
+        logging_configuration: DeepCloneUtils.deep_copy(@logging_configuration)
+      )
+    end
   end
 end

data/lib/apimatic-core/http/http_call_context.rb

@@ -0,0 +1,50 @@
+module CoreLibrary
+  # HttpCallContext is a callback class used to capture the HTTP request and response
+  # lifecycle during an API call. It is intended to be passed to an HTTP client or controller
+  # that supports pre- and post-request hooks.
+  #
+  # This class stores references to the request and response objects, making them
+  # accessible after the API call is completed. This can be useful for debugging,
+  # logging, or validation purposes.
+  #
+  # Example usage:
+  #   context = CoreLibrary::HttpCallContext.new
+  #   client.execute_request(request, context)
+  #   puts context.request  # Inspect the HttpRequest
+  #   puts context.response # Inspect the HttpResponse
+  class HttpCallContext < HttpCallback
+    # @return [HttpRequest, nil] The HTTP request object that was sent.
+    attr_reader :request
+
+    # @return [HttpResponse, nil] The HTTP response object that was received.
+    attr_reader :response
+
+    # Initializes a new instance of HttpCallContext.
+    #
+    # @param user_provided_http_callback [HttpCallback, nil] An optional user-defined callback
+    #   that will be triggered before and after the HTTP request.
+    def initialize(user_provided_http_callback = nil)
+      @request = nil
+      @response = nil
+      @http_callback = user_provided_http_callback
+    end
+
+    # Called before making the HTTP request.
+    # Stores the request and invokes the user-provided callback, if any.
+    #
+    # @param request [HttpRequest] The request object to be sent to the HttpClient.
+    def on_before_request(request)
+      @request = request
+      @http_callback&.on_before_request(request)
+    end
+
+    # Called after receiving the HTTP response.
+    # Stores the response and invokes the user-provided callback, if any.
+    #
+    # @param response [HttpResponse] The HttpResponse of the API call.
+    def on_after_response(response)
+      @response = response
+      @http_callback&.on_after_response(response)
+    end
+  end
+end

data/lib/apimatic-core/http/response/http_response.rb

@@ -1,6 +1,9 @@
 module CoreLibrary
   # Http response received.
   class HttpResponse
+    BODY_PARAM_POINTER = '$response.body'.freeze
+    HEADER_PARAM_POINTER = '$response.headers'.freeze
+
     attr_reader :status_code, :reason_phrase, :headers, :raw_body, :request
 
     # The constructor
@@ -20,5 +23,31 @@ module CoreLibrary
       @raw_body = raw_body
       @request = request
     end
+
+    # Resolves a JSON pointer against either the response body or response headers.
+    #
+    # This method is useful when extracting a specific value from an API response using a JSON pointer.
+    # It determines whether to extract from the body or headers based on the prefix in the pointer.
+    #
+    # @param json_pointer [String] A JSON pointer string (e.g., '/body/data/id' or '/headers/x-request-id').
+    # @return [Object, nil] The value located at the specified JSON pointer,
+    #                       or nil if not found or prefix is unrecognized.
+    def get_value_by_json_pointer(json_pointer)
+      param_pointer, field_pointer = JsonPointerHelper.split_into_parts(json_pointer)
+
+      value = case param_pointer
+              when HEADER_PARAM_POINTER
+                JsonPointerHelper.get_value_by_json_pointer(@headers, field_pointer)
+              when BODY_PARAM_POINTER
+                JsonPointerHelper.get_value_by_json_pointer(
+                  ApiHelper.json_deserialize(@raw_body),
+                  field_pointer
+                )
+              else
+                nil
+              end
+
+      value.nil? || (value.is_a? JsonPointer::NotFound) ? nil : value
+    end
   end
 end

data/lib/apimatic-core/pagination/paginated_data.rb

@@ -0,0 +1,137 @@
+module CoreLibrary
+  # Iterator class for handling paginated API responses.
+  #
+  # Provides methods to iterate over items and pages, fetch next pages using defined pagination strategies,
+  # and access the latest HTTP response and request builder.
+  class PaginatedData
+    include Enumerable
+
+    attr_reader :page_size
+
+    def initialize(api_call, paginated_items_converter)
+      raise ArgumentError, 'paginated_items_converter cannot be nil' if paginated_items_converter.nil?
+
+      @api_call = api_call
+      @paginated_items_converter = paginated_items_converter
+      @initial_request_builder = api_call.request_builder
+      @pagination_strategies = @api_call.pagination_strategy_list
+      @http_call_context = HttpCallContext.new(
+        @api_call.global_configuration.client_configuration.http_callback
+      )
+      http_client_config = @api_call.global_configuration.client_configuration.clone_with(
+        http_callback: @http_call_context
+      )
+      @global_configuration = @api_call.global_configuration.clone_with(
+        client_configuration: http_client_config
+      )
+
+      @last_request_builder = nil
+      @locked_strategy = nil
+      @page_size = 0
+    end
+
+    # Returns the most recent HTTP response received during pagination.
+    def last_response
+      @last_request_builder.nil? ? nil : @http_call_context.response
+    end
+
+    # Returns the appropriate request builder for the current pagination state.
+    def request_builder
+      @last_request_builder || @initial_request_builder
+    end
+
+    # Enables iteration over individual items.
+    def each
+      return enum_for(:each) unless block_given?
+
+      paginated_data = clone
+      current_index = 0
+      items = []
+
+      loop do
+        if current_index < paginated_data.page_size
+          yield items[current_index]
+          current_index += 1
+        else
+          response = paginated_data.fetch_next_page
+          break if response.nil?
+
+          items = @paginated_items_converter.call(response.data)
+          break if items.nil? || items.empty?
+
+          paginated_data.page_size = items.length
+          current_index = 0
+        end
+      end
+    end
+
+    # Yields each page of the paginated response.
+    def pages
+      Enumerator.new do |page|
+        paginated_data = clone
+
+        loop do
+          response = paginated_data.fetch_next_page
+          break if response.nil?
+
+          items = @paginated_items_converter.call(response.data)
+          break if items.nil? || items.empty?
+
+          paginated_data.page_size = items.length
+
+          page << response
+        end
+      end
+    end
+
+    # Returns a new independent PaginatedData instance.
+    def clone
+      cloned_api_call = @api_call.clone_with(request_builder: @initial_request_builder)
+      PaginatedData.new(cloned_api_call, @paginated_items_converter)
+    end
+
+    protected
+
+    attr_accessor :items, :current_index, :paged_response
+    attr_writer :page_size
+
+    # Fetches the next page using the appropriate pagination strategy.
+    def fetch_next_page
+      return execute_strategy(@locked_strategy) unless @locked_strategy.nil?
+
+      @pagination_strategies.each do |pagination_strategy|
+        response = execute_strategy(pagination_strategy)
+        next if response.nil?
+
+        @locked_strategy ||= get_locked_strategy
+        return response
+      end
+
+      nil
+    end
+
+    # Executes a pagination strategy: builds the request, performs the API call,
+    # and applies response metadata.
+    def execute_strategy(pagination_strategy)
+      _request_builder = pagination_strategy.apply(self)
+      return nil if _request_builder.nil?
+
+      @last_request_builder = _request_builder
+
+      response = @api_call.clone_with(
+        global_configuration: @global_configuration,
+        request_builder: _request_builder
+      ).execute
+
+      pagination_strategy.apply_metadata_wrapper(response)
+    end
+
+    # Finds and returns the first applicable pagination strategy
+    # based on the current response.
+    def get_locked_strategy
+      @pagination_strategies.find do |pagination_strategy|
+        pagination_strategy.applicable?(last_response)
+      end
+    end
+  end
+end

data/lib/apimatic-core/pagination/pagination_strategy.rb

@@ -0,0 +1,46 @@
+module CoreLibrary
+  # Abstract base class for implementing pagination strategies.
+  #
+  # Provides methods to initialize with pagination metadata, apply pagination logic to request builders,
+  # and update request builders with new pagination parameters based on JSON pointers.
+  class PaginationStrategy
+    attr_reader :metadata_wrapper
+
+    # Initializes the PaginationStrategy with the provided metadata wrapper.
+    #
+    # @param metadata_wrapper [Object] An object containing pagination metadata. Must not be nil.
+    # @raise [ArgumentError] If metadata_wrapper is nil.
+    def initialize(metadata_wrapper)
+      raise ArgumentError, 'Metadata wrapper for the pagination cannot be nil' if metadata_wrapper.nil?
+
+      @metadata_wrapper = metadata_wrapper
+    end
+
+    # Checks whether the pagination strategy is a valid candidate based on the given HTTP response.
+    #
+    # @param response [HttpResponse] The response data from the previous API call.
+    # @return [boolean] True if this strategy is valid based on the given HTTP response..
+    # @raise [NotImplementedError] This method must be implemented in a subclass.
+    def applicable?(response)
+      raise NotImplementedError, 'Subclasses must implement #is_applicable'
+    end
+
+    # Modifies the request builder to fetch the next page of results based on the provided paginated data.
+    #
+    # @param paginated_data [Object] The response data from the previous API call.
+    # @return [Object] An updated request builder configured for the next page request.
+    # @raise [NotImplementedError] This method must be implemented in a subclass.
+    def apply(paginated_data)
+      raise NotImplementedError, 'Subclasses must implement #apply'
+    end
+
+    # Processes the paged API response using the metadata wrapper.
+    #
+    # @param paged_response [Object] The response object containing paginated data.
+    # @return [Object] The processed response with applied pagination metadata.
+    # @raise [NotImplementedError] This method must be implemented in a subclass.
+    def apply_metadata_wrapper(paged_response)
+      raise NotImplementedError, 'Subclasses must implement #apply_metadata_wrapper'
+    end
+  end
+end

data/lib/apimatic-core/pagination/strategies/cursor_pagination.rb

@@ -0,0 +1,72 @@
+module CoreLibrary
+  # Implements a cursor-based pagination strategy for API responses.
+  #
+  # This class manages the extraction and injection of cursor values between API requests and responses,
+  # enabling seamless traversal of paginated data.
+  class CursorPagination < PaginationStrategy
+    # Initializes a CursorPagination instance with the specified output and input pointers and a metadata wrapper.
+    #
+    # Validates that both input and output pointers are provided.
+    #
+    # @param output [String] JSON pointer to extract the cursor from the API response.
+    # @param input [String] JSON pointer indicating where to set the cursor in the request.
+    # @param metadata_wrapper [Proc] A callable to wrap paged responses with additional metadata.
+    # @raise [ArgumentError] If either input or output is nil.
+    def initialize(output, input, metadata_wrapper)
+      super metadata_wrapper
+
+      raise ArgumentError, 'Input pointer for cursor based pagination cannot be nil' if input.nil?
+      raise ArgumentError, 'Output pointer for cursor based pagination cannot be nil' if output.nil?
+
+      @output = output
+      @input = input
+      @cursor_value = nil
+    end
+
+    # Determines whether the cursor pagination strategy is applicable
+    # based on the given HTTP response.
+    #
+    # @param [HttpResponse, nil] response The response from the previous API call.
+    # @return [Boolean] true if this strategy is applicable based on the response; false otherwise.
+    def applicable?(response)
+      return true if response.nil?
+
+      @cursor_value = response.get_value_by_json_pointer(@output)
+
+      !@cursor_value.nil?
+    end
+
+    # Advances the pagination by updating the request builder with the next cursor value.
+    #
+    # If there is no previous response, initializes the cursor from the request builder.
+    # Otherwise, extracts the cursor from the last response using the configured output pointer.
+    #
+    # @param paginated_data [Object] An object containing the last response and request builder.
+    # @return [Object, nil] A new request builder for the next page, or nil if pagination is complete.
+    def apply(paginated_data)
+      last_response = paginated_data.last_response
+      request_builder = paginated_data.request_builder
+
+      # If there is no response yet, this is the first page
+      if last_response.nil?
+        @cursor_value = request_builder.get_parameter_value_by_json_pointer(@input).to_s
+
+        return request_builder
+      end
+
+      @cursor_value = last_response.get_value_by_json_pointer(@output)
+
+      return nil if @cursor_value.nil?
+
+      request_builder.get_updated_request_by_json_pointer(@input, @cursor_value)
+    end
+
+    # Applies the configured metadata wrapper to the paged response, including the current cursor value.
+    #
+    # @param paged_response [Object] The response object from the current page.
+    # @return [Object] The result of the metadata wrapper applied to the paged response and cursor value.
+    def apply_metadata_wrapper(paged_response)
+      @metadata_wrapper.call(paged_response, @cursor_value)
+    end
+  end
+end

data/lib/apimatic-core/pagination/strategies/link_pagination.rb

@@ -0,0 +1,67 @@
+module CoreLibrary
+  # Implements a pagination strategy that extracts the next page link from API responses using a JSON pointer.
+  #
+  # This class updates the request builder with query parameters from the next page link
+  # and applies a metadata wrapper to the paged response.
+  class LinkPagination < PaginationStrategy
+    # Initializes a LinkPagination instance with the given next link pointer and metadata wrapper.
+    #
+    # @param next_link_pointer [String] JSON pointer to extract the next page link from the API response.
+    # @param metadata_wrapper [Proc] A callable to wrap the paged response metadata.
+    # @raise [ArgumentError] If next_link_pointer is nil.
+    def initialize(next_link_pointer, metadata_wrapper)
+      super(metadata_wrapper)
+
+      raise ArgumentError, 'Next link pointer for cursor based pagination cannot be nil' if next_link_pointer.nil?
+
+      @next_link_pointer = next_link_pointer
+      @next_link = nil
+    end
+
+    # Determines whether the link pagination strategy is applicable
+    # based on the given HTTP response.
+    #
+    # @param [HttpResponse, nil] response The response from the previous API call.
+    # @return [Boolean] true if this strategy is applicable based on the response; false otherwise.
+    def applicable?(response)
+      return true if response.nil?
+
+      @next_link = response.get_value_by_json_pointer(@next_link_pointer)
+
+      !@next_link.nil?
+    end
+
+    # Updates the request builder with query parameters from the next page link extracted from the last API response.
+    #
+    # @param paginated_data [Object] An object containing the last API response and the current request builder.
+    # @return [Object, nil] A new request builder with updated query parameters, or nil if no next link is found.
+    def apply(paginated_data)
+      last_response = paginated_data.last_response
+      request_builder = paginated_data.request_builder
+
+      # If there is no response yet, this is the first page
+      if last_response.nil?
+        @next_link = nil
+        return request_builder
+      end
+
+      @next_link = last_response.get_value_by_json_pointer(@next_link_pointer)
+
+      return nil if @next_link.nil?
+
+      query_params = ApiHelper.get_query_parameters(@next_link)
+      updated_query_params = DeepCloneUtils.deep_copy(request_builder.query_params)
+      updated_query_params.merge!(query_params)
+
+      request_builder.clone_with(query_params: updated_query_params)
+    end
+
+    # Applies the metadata wrapper to the paged response, including the next page link.
+    #
+    # @param paged_response [Object] The API response object for the current page.
+    # @return [Object] The result of the metadata wrapper, typically containing the response and next link.
+    def apply_metadata_wrapper(paged_response)
+      @metadata_wrapper.call(paged_response, @next_link)
+    end
+  end
+end