surge_api 0.1.0

data/lib/surge_api/internal/type/hash_of.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Internal
+    module Type
+      # @api private
+      #
+      # @abstract
+      #
+      # @generic Elem
+      #
+      # Hash of items of a given type.
+      class HashOf
+        include SurgeAPI::Internal::Type::Converter
+        include SurgeAPI::Internal::Util::SorbetRuntimeSupport
+
+        private_class_method :new
+
+        # @overload [](type_info, spec = {})
+        #
+        # @param type_info [Hash{Symbol=>Object}, Proc, SurgeAPI::Internal::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        #
+        # @return [self]
+        def self.[](...) = new(...)
+
+        # @api public
+        #
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ===(other)
+          type = item_type
+          case other
+          in Hash
+            other.all? do |key, val|
+              case [key, val]
+              in [Symbol | String, ^type]
+                true
+              else
+                false
+              end
+            end
+          else
+            false
+          end
+        end
+
+        # @api public
+        #
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ==(other)
+          # rubocop:disable Layout/LineLength
+          other.is_a?(SurgeAPI::Internal::Type::HashOf) && other.nilable? == nilable? && other.item_type == item_type
+          # rubocop:enable Layout/LineLength
+        end
+
+        # @api public
+        #
+        # @return [Integer]
+        def hash = [self.class, item_type].hash
+
+        # @api private
+        #
+        # @param value [Hash{Object=>Object}, Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Class<StandardError>] :error
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Hash{Symbol=>Object}, Object]
+        def coerce(value, state:)
+          exactness = state.fetch(:exactness)
+
+          unless value.is_a?(Hash)
+            exactness[:no] += 1
+            state[:error] = TypeError.new("#{value.class} can't be coerced into #{Hash}")
+            return value
+          end
+
+          target = item_type
+          exactness[:yes] += 1
+          value
+            .to_h do |key, val|
+              k = key.is_a?(String) ? key.to_sym : key
+              v =
+                case [nilable?, val]
+                in [true, nil]
+                  exactness[:yes] += 1
+                  nil
+                else
+                  SurgeAPI::Internal::Type::Converter.coerce(target, val, state: state)
+                end
+
+              exactness[:no] += 1 unless k.is_a?(Symbol)
+              [k, v]
+            end
+        end
+
+        # @api private
+        #
+        # @param value [Hash{Object=>Object}, Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean] :can_retry
+        #
+        # @return [Hash{Symbol=>Object}, Object]
+        def dump(value, state:)
+          target = item_type
+          if value.is_a?(Hash)
+            value.transform_values do
+              SurgeAPI::Internal::Type::Converter.dump(target, _1, state: state)
+            end
+          else
+            super
+          end
+        end
+
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          T::Hash[SurgeAPI::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(item_type)]
+        end
+
+        # @api private
+        #
+        # @return [generic<Elem>]
+        protected def item_type = @item_type_fn.call
+
+        # @api private
+        #
+        # @return [Boolean]
+        protected def nilable? = @nilable
+
+        # @api private
+        #
+        # @param type_info [Hash{Symbol=>Object}, Proc, SurgeAPI::Internal::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        def initialize(type_info, spec = {})
+          @item_type_fn = SurgeAPI::Internal::Type::Converter.type_info(type_info || spec)
+          @meta = SurgeAPI::Internal::Type::Converter.meta_info(type_info, spec)
+          @nilable = spec.fetch(:nil?, false)
+        end
+
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          items = SurgeAPI::Internal::Type::Converter.inspect(item_type, depth: depth.succ)
+
+          "#{self.class}[#{[items, nilable? ? 'nil' : nil].compact.join(' | ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/surge_api/internal/type/request_parameters.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Internal
+    module Type
+      # @api private
+      module RequestParameters
+        # @!attribute request_options
+        # Options to specify HTTP behaviour for this request.
+        #
+        #   @return [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+
+        # @param mod [Module]
+        def self.included(mod)
+          raise ArgumentError.new(mod) unless mod <= SurgeAPI::Internal::Type::BaseModel
+
+          mod.optional(:request_options, SurgeAPI::RequestOptions)
+        end
+
+        # @api private
+        module Converter
+          # @api private
+          #
+          # @param params [Object]
+          #
+          # @return [Array(Object, Hash{Symbol=>Object})]
+          def dump_request(params)
+            state = {can_retry: true}
+            case (dumped = dump(params, state: state))
+            in Hash
+              options = SurgeAPI::Internal::Util.coerce_hash!(dumped[:request_options]).to_h
+              request_options = state.fetch(:can_retry) ? options : {**options, max_retries: 0}
+              [dumped.except(:request_options), request_options]
+            else
+              [dumped, nil]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/surge_api/internal/type/union.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Internal
+    module Type
+      # @api private
+      #
+      # @example
+      #   # `unwrap_webhook_event` is a `SurgeAPI::UnwrapWebhookEvent`
+      #   case unwrap_webhook_event
+      #   when SurgeAPI::CallEndedWebhookEvent
+      #     puts(unwrap_webhook_event.account_id)
+      #   when SurgeAPI::CampaignApprovedWebhookEvent
+      #     puts(unwrap_webhook_event.data)
+      #   when SurgeAPI::ConversationCreatedWebhookEvent
+      #     puts(unwrap_webhook_event.timestamp)
+      #   else
+      #     puts(unwrap_webhook_event)
+      #   end
+      module Union
+        include SurgeAPI::Internal::Type::Converter
+        include SurgeAPI::Internal::Util::SorbetRuntimeSupport
+
+        # @api private
+        #
+        # All of the specified variant info for this union.
+        #
+        # @return [Array<Array(Symbol, Proc, Hash{Symbol=>Object})>]
+        private def known_variants = (@known_variants ||= [])
+
+        # @api private
+        #
+        # @return [Array<Array(Symbol, Object, Hash{Symbol=>Object})>]
+        protected def derefed_variants
+          known_variants.map { |key, variant_fn, meta| [key, variant_fn.call, meta] }
+        end
+
+        # All of the specified variants for this union.
+        #
+        # @return [Array<Object>]
+        def variants = derefed_variants.map { _2 }
+
+        # @api private
+        #
+        # @param property [Symbol]
+        private def discriminator(property)
+          case property
+          in Symbol
+            @discriminator = property
+          end
+        end
+
+        # @api private
+        #
+        # @param key [Symbol, Hash{Symbol=>Object}, Proc, SurgeAPI::Internal::Type::Converter, Class]
+        #
+        # @param spec [Hash{Symbol=>Object}, Proc, SurgeAPI::Internal::Type::Converter, Class] .
+        #
+        #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+        #
+        #   @option spec [Proc] :enum
+        #
+        #   @option spec [Proc] :union
+        #
+        #   @option spec [Boolean] :"nil?"
+        private def variant(key, spec = nil)
+          meta = SurgeAPI::Internal::Type::Converter.meta_info(nil, spec)
+          variant_info =
+            case key
+            in Symbol
+              [key, SurgeAPI::Internal::Type::Converter.type_info(spec), meta]
+            in Proc | SurgeAPI::Internal::Type::Converter | Class | Hash
+              [nil, SurgeAPI::Internal::Type::Converter.type_info(key), meta]
+            end
+
+          known_variants << variant_info
+        end
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @return [SurgeAPI::Internal::Type::Converter, Class, nil]
+        private def resolve_variant(value)
+          case [@discriminator, value]
+          in [_, SurgeAPI::Internal::Type::BaseModel]
+            value.class
+          in [Symbol, Hash]
+            key = value.fetch(@discriminator) do
+              value.fetch(@discriminator.to_s, SurgeAPI::Internal::OMIT)
+            end
+
+            return nil if key == SurgeAPI::Internal::OMIT
+
+            key = key.to_sym if key.is_a?(String)
+            _, found = known_variants.find { |k,| k == key }
+            found&.call
+          else
+            nil
+          end
+        end
+
+        # rubocop:disable Style/HashEachMethods
+        # rubocop:disable Style/CaseEquality
+
+        # @api public
+        #
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ===(other)
+          known_variants.any? do |_, variant_fn|
+            variant_fn.call === other
+          end
+        end
+
+        # @api public
+        #
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def ==(other)
+          SurgeAPI::Internal::Type::Union === other && other.derefed_variants == derefed_variants
+        end
+
+        # @api public
+        #
+        # @return [Integer]
+        def hash = variants.hash
+
+        # @api private
+        #
+        # Tries to efficiently coerce the given value to one of the known variants.
+        #
+        # If the value cannot match any of the known variants, the coercion is considered
+        # non-viable and returns the original value.
+        #
+        # @param value [Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
+        #
+        #   @option state [Hash{Symbol=>Object}] :exactness
+        #
+        #   @option state [Class<StandardError>] :error
+        #
+        #   @option state [Integer] :branched
+        #
+        # @return [Object]
+        def coerce(value, state:)
+          if (target = resolve_variant(value))
+            return SurgeAPI::Internal::Type::Converter.coerce(target, value, state: state)
+          end
+
+          strictness = state.fetch(:strictness)
+          exactness = state.fetch(:exactness)
+
+          alternatives = []
+          known_variants.each do |_, variant_fn|
+            target = variant_fn.call
+            exact = state[:exactness] = {yes: 0, no: 0, maybe: 0}
+            state[:branched] += 1
+
+            coerced = SurgeAPI::Internal::Type::Converter.coerce(target, value, state: state)
+            yes, no, maybe = exact.values
+            if (no + maybe).zero? || (!strictness && yes.positive?)
+              exact.each { exactness[_1] += _2 }
+              state[:exactness] = exactness
+              return coerced
+            elsif maybe.positive?
+              alternatives << [[-yes, -maybe, no], exact, coerced]
+            end
+          end
+
+          case alternatives.sort_by!(&:first)
+          in []
+            exactness[:no] += 1
+            state[:error] = ArgumentError.new("no matching variant for #{value.inspect}")
+            value
+          in [[_, exact, coerced], *]
+            exact.each { exactness[_1] += _2 }
+            coerced
+          end
+            .tap { state[:exactness] = exactness }
+        ensure
+          state[:strictness] = strictness
+        end
+
+        # @api private
+        #
+        # @param value [Object]
+        #
+        # @param state [Hash{Symbol=>Object}] .
+        #
+        #   @option state [Boolean] :can_retry
+        #
+        # @return [Object]
+        def dump(value, state:)
+          if (target = resolve_variant(value))
+            return SurgeAPI::Internal::Type::Converter.dump(target, value, state: state)
+          end
+
+          known_variants.each do
+            target = _2.call
+            return SurgeAPI::Internal::Type::Converter.dump(target, value, state: state) if target === value
+          end
+
+          super
+        end
+
+        # @api private
+        #
+        # @return [Object]
+        def to_sorbet_type
+          types = variants.map { SurgeAPI::Internal::Util::SorbetRuntimeSupport.to_sorbet_type(_1) }.uniq
+          case types
+          in []
+            T.noreturn
+          in [type]
+            type
+          else
+            T.any(*types)
+          end
+        end
+
+        # rubocop:enable Style/CaseEquality
+        # rubocop:enable Style/HashEachMethods
+
+        # @api private
+        #
+        # @param depth [Integer]
+        #
+        # @return [String]
+        def inspect(depth: 0)
+          if depth.positive?
+            return is_a?(Module) ? super() : self.class.name
+          end
+
+          members = variants.map { SurgeAPI::Internal::Type::Converter.inspect(_1, depth: depth.succ) }
+          prefix = is_a?(Module) ? name : self.class.name
+
+          "#{prefix}[#{members.join(' | ')}]"
+        end
+      end
+    end
+  end
+end

data/lib/surge_api/internal/type/unknown.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Internal
+    module Type
+      # @api private
+      #
+      # @abstract
+      #
+      # When we don't know what to expect for the value.
+      class Unknown
+        extend SurgeAPI::Internal::Type::Converter
+        extend SurgeAPI::Internal::Util::SorbetRuntimeSupport
+
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        private_class_method :new
+
+        # @api public
+        #
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def self.===(other) = true
+
+        # @api public
+        #
+        # @param other [Object]
+        #
+        # @return [Boolean]
+        def self.==(other) = other.is_a?(Class) && other <= SurgeAPI::Internal::Type::Unknown
+
+        class << self
+          # @api private
+          #
+          # No coercion needed for Unknown type.
+          #
+          # @param value [Object]
+          #
+          # @param state [Hash{Symbol=>Object}] .
+          #
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
+          #
+          #   @option state [Hash{Symbol=>Object}] :exactness
+          #
+          #   @option state [Class<StandardError>] :error
+          #
+          #   @option state [Integer] :branched
+          #
+          # @return [Object]
+          def coerce(value, state:)
+            state.fetch(:exactness)[:yes] += 1
+            value
+          end
+
+          # @!method dump(value, state:)
+          #   @api private
+          #
+          #   @param value [Object]
+          #
+          #   @param state [Hash{Symbol=>Object}] .
+          #
+          #     @option state [Boolean] :can_retry
+          #
+          #   @return [Object]
+
+          # @api private
+          #
+          # @return [Object]
+          def to_sorbet_type
+            T.anything
+          end
+        end
+
+        # rubocop:enable Lint/UnusedMethodArgument
+      end
+    end
+  end
+end