apimatic_core 0.3.15 → 0.3.16

data/lib/apimatic-core/utilities/json_pointer.rb

@@ -0,0 +1,257 @@
+module CoreLibrary
+  # The `JsonPointer` class provides a utility for querying, modifying, and deleting
+  # values within deeply nested Ruby Hashes and Arrays using JSON Pointer syntax (RFC 6901),
+  # extended with support for wildcards (`~`) and array-push semantics (`-`).
+  #
+  # ## Features
+  # - Navigate and retrieve deeply nested values using JSON Pointer paths.
+  # - Supports complex structures containing both Arrays and Hashes.
+  # - Wildcard support (`~`) for batch operations across multiple elements.
+  # - Special key (`-`) for appending to arrays (push behavior).
+  # - Optional `:symbolize_keys` behavior to convert pointer fragments to symbols.
+  #
+  # ## Example Usage
+  #   data = { "a" => [{ "b" => 1 }, { "b" => 2 }] }
+  #   pointer = JsonPointer.new(data, "/a/~1/b")
+  #   value = pointer.value  # => 2
+  #
+  #   pointer.value = 42
+  #   pointer.delete
+  #
+  # ## Limitations
+  # - This class operates directly on mutable input data structures.
+  # - Wildcards and array push keys are not part of the official JSON Pointer spec.
+  #
+  # @example Initialize and read value
+  #   JsonPointer.new({ "foo" => { "bar" => 42 } }, "/foo/bar").value # => 42
+  #
+  class JsonPointer
+    NotFound = Class.new
+    WILDCARD = '~'.freeze
+    ARRAY_PUSH_KEY = '-'.freeze
+
+    def self.escape_fragment(fragment)
+      return fragment if fragment == WILDCARD
+
+      fragment.gsub(/~/, '~0').gsub(%r{/}, '~1')
+    end
+
+    def self.unescape_fragment(fragment)
+      fragment.gsub(/~1/, '/').gsub(/~0/, '~')
+    end
+
+    def self.join_fragments(fragments)
+      fragments.map { |f| escape_fragment(f) }.join('/')
+    end
+
+    def initialize(hash, path, options = {})
+      @hash = hash
+      @path = path
+      @options = options
+    end
+
+    def value
+      get_member_value
+    end
+
+    def value=(new_value)
+      set_member_value(new_value)
+    end
+
+    def delete
+      delete_member
+    end
+
+    def exists?
+      _exists = false
+      get_target_member(@hash, path_fragments.dup) do |target, options = {}|
+        if options[:wildcard]
+          _exists = target.any? { |t| !t.nil? && !t.is_a?(NotFound) }
+        else
+          _exists = true unless target.is_a?(NotFound)
+        end
+      end
+      _exists
+    end
+
+    private
+
+    def get_member_value(obj = @hash, fragments = path_fragments.dup)
+      return obj if fragments.empty?
+
+      fragment = fragments.shift
+      case obj
+      when Hash
+        get_member_value(obj[fragment_to_key(fragment)], fragments)
+      when Array
+        if fragment == WILDCARD
+          obj.map { |i| get_member_value(i, fragments.dup) }
+        else
+          get_member_value(obj[fragment_to_index(fragment)], fragments)
+        end
+      else
+        NotFound.new
+      end
+    end
+
+    def get_target_member(obj, fragments, options = {}, &block)
+      return yield(obj, {}) if fragments.empty?
+
+      case obj
+      when Hash
+        get_target_member_if_hash(obj, fragments, options, &block)
+      when Array
+        get_target_member_if_array(obj, fragments, options, &block)
+      else
+        NotFound.new
+      end
+    end
+
+    def get_target_member_if_hash(obj, fragments, options = {}, &block)
+      fragment = fragments.shift
+      key = fragment_to_key(fragment)
+      obj = if options[:create_missing]
+              obj[key] ||= {}
+            else
+              obj.key?(key) ? obj[key] : NotFound.new
+            end
+
+      get_target_member(obj, fragments, options, &block)
+    end
+
+    def get_target_member_if_array(obj, fragments, options = {}, &block)
+      fragment = fragments.shift
+      if fragment == WILDCARD
+        if obj.any?
+          targets = obj.map do |i|
+            get_target_member(i || {}, fragments.dup, options) { |t| t }
+          end
+          yield(targets, wildcard: true)
+        else
+          NotFound.new
+        end
+      else
+        index = fragment_to_index(fragment)
+        obj = if options[:create_missing]
+                obj[index] ||= {}
+              else
+                index >= obj.size ? NotFound.new : obj[index]
+              end
+
+        get_target_member(obj, fragments, &block)
+      end
+    end
+
+    def set_member_value(new_value)
+      obj = @hash
+      fragments = path_fragments.dup
+
+      return if fragments.empty?
+
+      target_fragment = fragments.pop
+      target_parent_fragment = fragments.pop if target_fragment == ARRAY_PUSH_KEY
+
+      get_target_member(obj, fragments.dup, create_missing: true) do |target, options = {}|
+        if options[:wildcard]
+          fragments = fragments.each_with_object([]) do |memo, f|
+            break memo if f == WILDCARD
+
+            memo << f
+            memo
+          end
+
+          path = join_fragments(fragments)
+          pointer = self.class.new(obj, path, @options)
+          pointer.value.push({ fragment_to_key(target_fragment) => new_value })
+        elsif target_fragment == ARRAY_PUSH_KEY
+          key = case target
+                when Hash
+                  fragment_to_key(target_parent_fragment)
+                when Array
+                  fragment_to_index(target_parent_fragment)
+                else
+                  nil
+                end
+
+          return unless key
+
+          target[key] ||= []
+          return unless target[key].is_a?(Array)
+
+          target[key].push(new_value)
+          return new_value
+        else
+          case target
+          when Hash
+            target[fragment_to_key(target_fragment)] = new_value
+          when Array
+            # NOTE: Using `Array#insert(index, value)` here shifts existing elements to the right
+            # instead of replacing the value at the index. If the index is out of bounds,
+            # it fills the gap with `nil`.
+            target.insert(fragment_to_index(target_fragment), new_value)
+          else
+            nil
+          end
+        end
+      end
+    end
+
+    def delete_member
+      obj = @hash
+      fragments = path_fragments.dup
+
+      return if fragments.empty?
+
+      target_fragment = fragments.pop
+      get_target_member(obj, fragments) do |target, options = {}|
+        if options[:wildcard]
+          target.each do |t|
+            case t
+            when Hash
+              t.delete(fragment_to_key(target_fragment))
+            else
+              nil
+            end
+          end
+        else
+          case target
+          when Hash
+            target.delete(fragment_to_key(target_fragment))
+          when Array
+            if target_fragment == WILDCARD
+              target.replace([])
+            else
+              target.delete_at(fragment_to_index(target_fragment))
+            end
+          else
+            nil
+          end
+        end
+      end
+    end
+
+    def path_fragments
+      @path_fragments ||= @path.sub(%r{\A/}, '').split('/').map { |fragment| unescape_fragment(fragment) }
+    end
+
+    def escape_fragment(fragment)
+      JsonPointer.escape_fragment(fragment)
+    end
+
+    def unescape_fragment(fragment)
+      JsonPointer.unescape_fragment(fragment)
+    end
+
+    def join_fragments(fragments)
+      JsonPointer.join_fragments(fragments)
+    end
+
+    def fragment_to_key(fragment)
+      @options[:symbolize_keys] ? fragment.to_sym : fragment
+    end
+
+    def fragment_to_index(fragment)
+      fragment.to_i
+    end
+  end
+end

data/lib/apimatic-core/utilities/json_pointer_helper.rb

@@ -1,134 +1,58 @@
 module CoreLibrary
   # A utility for json specific operations.
   class JsonPointerHelper
-    NotFound = Class.new
-    WILDCARD = '~'.freeze
-    ARRAY_PUSH_KEY = '-'.freeze
-
-    def self.escape_fragment(fragment)
-      return fragment if fragment == WILDCARD
-
-      fragment.gsub(/~/, '~0').gsub(%r{/}, '~1')
-    end
-
-    def self.unescape_fragment(fragment)
-      fragment.gsub(/~1/, '/').gsub(/~0/, '~')
-    end
-
-    def initialize(hash, path, options = {})
-      @hash = hash
-      @path = path
-      @options = options
-    end
-
-    def value
-      get_member_value
-    end
-
-    def exists?
-      _exists = false
-      get_target_member(@hash, path_fragments.dup) do |target, options = {}|
-        if options[:wildcard]
-          _exists = target.any? { |t| !t.nil? && !t.is_a?(NotFound) }
-        else
-          _exists = true unless target.is_a?(NotFound)
-        end
-      end
-      _exists
-    end
-
-    private
-
-    def get_member_value(obj = @hash, fragments = path_fragments.dup)
-      return obj if fragments.empty?
-
-      fragment = fragments.shift
-      case obj
-      when Hash
-        get_member_value(obj[fragment_to_key(fragment)], fragments)
-      when Array
-        if fragment == WILDCARD
-          obj.map { |i| get_member_value(i, fragments.dup) }
-        else
-          get_member_value(obj[fragment_to_index(fragment)], fragments)
-        end
-      else
-        NotFound.new
-      end
-    end
-
-    def get_target_member(obj, fragments, options = {}, &block)
-      return yield(obj, {}) if fragments.empty?
-
-      case obj
-      when Hash
-        get_target_member_if_hash(obj, fragments, options, &block)
-      when Array
-        get_target_member_if_array(obj, fragments, options, &block)
-      else
-        NotFound.new
+    # Splits a JSON pointer string into its prefix and field path components.
+    #
+    # @param [String, nil] json_pointer The JSON pointer string to split.
+    # @return [Array(String, String), Array(nil, nil)] A tuple with path prefix and field path,
+    #                                 or [nil, nil] if input is nil or empty.
+    def self.split_into_parts(json_pointer)
+      return [nil, nil] if json_pointer.nil? || json_pointer.strip.empty?
+
+      path_prefix, field_path = json_pointer.split('#', 2)
+      field_path ||= ''
+
+      [path_prefix, field_path]
+    end
+
+    # Retrieves a value from a hash using a JSON pointer.
+    #
+    # @param [Hash] hash The input hash to search.
+    # @param [String] pointer The JSON pointer string (e.g. "#/a/b").
+    # @param [Boolean] symbolize_keys Whether to symbolize keys in the hash while resolving.
+    #
+    # @return [Object, nil] The value at the given pointer path, or nil if not found or invalid.
+    def self.get_value_by_json_pointer(hash, pointer, symbolize_keys: false)
+      return nil if hash.nil? || pointer.nil? || pointer.strip.empty?
+
+      begin
+        json_pointer_resolver = JsonPointer.new(hash, pointer, symbolize_keys: symbolize_keys)
+        _value = json_pointer_resolver.value
+        _value.is_a?(JsonPointer::NotFound) ? nil : _value
+      rescue StandardError
+        # Optionally log error or re-raise specific known ones
+        nil
       end
     end
 
-    def get_target_member_if_hash(obj, fragments, options = {}, &block)
-      fragment = fragments.shift
-      key = fragment_to_key(fragment)
-      obj = if options[:create_missing]
-              obj[key] ||= {}
-            else
-              obj.key?(key) ? obj[key] : NotFound.new
-            end
-
-      get_target_member(obj, fragments, options, &block)
-    end
-
-    def get_target_member_if_array(obj, fragments, options = {}, &block)
-      fragment = fragments.shift
-      if fragment == WILDCARD
-        if obj.any?
-          targets = obj.map do |i|
-            get_target_member(i || {}, fragments.dup, options) do |t|
-              t
-            end
-          end
-          yield(targets, wildcard: true)
-        else
-          NotFound.new
-        end
-      else
-        index = fragment_to_index(fragment)
-        obj = if options[:create_missing]
-                obj[index] ||= {}
-              else
-                index >= obj.size ? NotFound.new : obj[index]
-              end
-
-        get_target_member(obj, fragments, &block)
+    # Retrieves a value from a hash using a JSON pointer.
+    #
+    # @param [Hash] hash The input hash to search.
+    # @param [String] pointer The JSON pointer string (e.g. "#/a/b").
+    # @param [Boolean] symbolize_keys Whether to symbolize keys in the hash while resolving.
+    #
+    # @return [Object, nil] The value at the given pointer path, or nil if not found or invalid.
+    def self.update_entry_by_json_pointer(hash, pointer, value, symbolize_keys: false)
+      return hash if hash.nil? || pointer.nil? || pointer.strip.empty?
+
+      begin
+        value_extractor = JsonPointer.new(hash, pointer, symbolize_keys: symbolize_keys)
+        value_extractor.value = value
+        hash
+      rescue StandardError
+        # Optionally log error or re-raise specific known ones
+        hash
       end
     end
-
-    def path_fragments
-      @path_fragments ||= @path.sub(%r{\A/}, '').split('/').map { |fragment| unescape_fragment(fragment) }
-    end
-
-    def escape_fragment(fragment)
-      JsonPointerHelper.escape_fragment(fragment)
-    end
-
-    def unescape_fragment(fragment)
-      JsonPointerHelper.unescape_fragment(fragment)
-    end
-
-    def fragment_to_key(fragment)
-      if @options[:symbolize_keys]
-        fragment.to_sym
-      else
-        fragment
-      end
-    end
-
-    def fragment_to_index(fragment)
-      fragment.to_i
-    end
   end
 end

data/lib/apimatic_core.rb

@@ -22,10 +22,18 @@ require_relative 'apimatic-core/logger/nil_sdk_logger'
 require_relative 'apimatic-core/logger/sdk_logger'
 require_relative 'apimatic-core/logger/configurations/api_logging_configuration'
 
+require_relative 'apimatic-core/pagination/paginated_data'
+require_relative 'apimatic-core/pagination/pagination_strategy'
+require_relative 'apimatic-core/pagination/strategies/cursor_pagination'
+require_relative 'apimatic-core/pagination/strategies/link_pagination'
+require_relative 'apimatic-core/pagination/strategies/offset_pagination'
+require_relative 'apimatic-core/pagination/strategies/page_pagination'
+
 require_relative 'apimatic-core/http/configurations/http_client_configuration'
 require_relative 'apimatic-core/http/request/http_request'
 require_relative 'apimatic-core/http/response/http_response'
 require_relative 'apimatic-core/http/response/api_response'
+require_relative 'apimatic-core/http/http_call_context'
 
 require_relative 'apimatic-core/types/parameter'
 require_relative 'apimatic-core/types/error_case'
@@ -50,6 +58,8 @@ require_relative 'apimatic-core/utilities/union_type_helper'
 require_relative 'apimatic-core/utilities/json_pointer_helper'
 require_relative 'apimatic-core/utilities/logger_helper'
 require_relative 'apimatic-core/utilities/constants'
+require_relative 'apimatic-core/utilities/deep_clone_utils'
+require_relative 'apimatic-core/utilities/json_pointer'
 
 require_relative 'apimatic-core/authentication/header_auth'
 require_relative 'apimatic-core/authentication/query_auth'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apimatic_core
 version: !ruby/object:Gem::Version
-  version: 0.3.15
+  version: 0.3.16
 platform: ruby
 authors:
 - APIMatic Ltd.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-08 00:00:00.000000000 Z
+date: 2025-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: apimatic_core_interfaces
@@ -170,6 +170,7 @@ files:
 - lib/apimatic-core/exceptions/one_of_validation_exception.rb
 - lib/apimatic-core/factories/http_response_factory.rb
 - lib/apimatic-core/http/configurations/http_client_configuration.rb
+- lib/apimatic-core/http/http_call_context.rb
 - lib/apimatic-core/http/request/http_request.rb
 - lib/apimatic-core/http/response/api_response.rb
 - lib/apimatic-core/http/response/http_response.rb
@@ -177,6 +178,12 @@ files:
 - lib/apimatic-core/logger/default_logger.rb
 - lib/apimatic-core/logger/nil_sdk_logger.rb
 - lib/apimatic-core/logger/sdk_logger.rb
+- lib/apimatic-core/pagination/paginated_data.rb
+- lib/apimatic-core/pagination/pagination_strategy.rb
+- lib/apimatic-core/pagination/strategies/cursor_pagination.rb
+- lib/apimatic-core/pagination/strategies/link_pagination.rb
+- lib/apimatic-core/pagination/strategies/offset_pagination.rb
+- lib/apimatic-core/pagination/strategies/page_pagination.rb
 - lib/apimatic-core/request_builder.rb
 - lib/apimatic-core/response_handler.rb
 - lib/apimatic-core/types/error_case.rb
@@ -195,7 +202,9 @@ files:
 - lib/apimatic-core/utilities/comparison_helper.rb
 - lib/apimatic-core/utilities/constants.rb
 - lib/apimatic-core/utilities/date_time_helper.rb
+- lib/apimatic-core/utilities/deep_clone_utils.rb
 - lib/apimatic-core/utilities/file_helper.rb
+- lib/apimatic-core/utilities/json_pointer.rb
 - lib/apimatic-core/utilities/json_pointer_helper.rb
 - lib/apimatic-core/utilities/logger_helper.rb
 - lib/apimatic-core/utilities/union_type_helper.rb