voltaria_sdk 2.34.5

data/lib/voltaria/internal/multipart/multipart_form_data.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Multipart
+      # @api private
+      class FormData
+        # @return [Array<FormDataPart>] The parts in this multipart form data.
+        attr_reader :parts
+
+        # @return [Encoder] The encoder for this multipart form data.
+        private attr_reader :encoder
+
+        def initialize
+          @encoder = Encoder.new
+          @parts = []
+        end
+
+        # Adds a new part to the multipart form data.
+        #
+        # @param name [String] The name of the form field
+        # @param value [String, Integer, Float, Boolean, #read] The value of the field
+        # @param content_type [String, nil] Optional content type
+        # @return [self] Returns self for chaining
+        def add(name:, value:, content_type: nil)
+          headers = content_type ? { "Content-Type" => content_type } : nil
+          add_part(FormDataPart.new(name:, value:, headers:))
+        end
+
+        # Adds a file to the multipart form data.
+        #
+        # @param name [String] The name of the form field
+        # @param file [#read] The file or readable object
+        # @param filename [String, nil] Optional filename (defaults to basename of path for File objects)
+        # @param content_type [String, nil] Optional content type (e.g. "image/png")
+        # @return [self] Returns self for chaining
+        def add_file(name:, file:, filename: nil, content_type: nil)
+          headers = content_type ? { "Content-Type" => content_type } : nil
+          filename ||= filename_for(file)
+          add_part(FormDataPart.new(name:, value: file, filename:, headers:))
+        end
+
+        # Adds a pre-created part to the multipart form data.
+        #
+        # @param part [FormDataPart] The part to add
+        # @return [self] Returns self for chaining
+        def add_part(part)
+          @parts << part
+          self
+        end
+
+        # Gets the content type string including the boundary.
+        #
+        # @return [String] The content type with boundary.
+        def content_type
+          @encoder.content_type
+        end
+
+        # Encode the multipart form data into a multipart/form-data payload.
+        #
+        # @return [String] The encoded body.
+        def encode
+          @encoder.encode(self)
+        end
+
+        private
+
+        def filename_for(file)
+          if file.is_a?(::File) || file.respond_to?(:path)
+            ::File.basename(file.path)
+          elsif file.respond_to?(:name)
+            file.name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/multipart/multipart_form_data_part.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Voltaria
+  module Internal
+    module Multipart
+      # @api private
+      class FormDataPart
+        attr_reader :name, :contents, :filename, :headers
+
+        # @param name [String] The name of the form field
+        # @param value [String, Integer, Float, Boolean, File, #read] The value of the field
+        # @param filename [String, nil] Optional filename for file uploads
+        # @param headers [Hash<String, String>, nil] Optional additional headers
+        def initialize(name:, value:, filename: nil, headers: nil)
+          @name = name
+          @contents = convert_to_content(value)
+          @filename = filename
+          @headers = headers
+        end
+
+        # Converts the part to a hash suitable for serialization.
+        #
+        # @return [Hash] A hash representation of the part
+        def to_hash
+          result = {
+            name: @name,
+            contents: @contents
+          }
+          result[:filename] = @filename if @filename
+          result[:headers] = @headers if @headers
+          result
+        end
+
+        private
+
+        # Converts various types of values to a content representation
+        # @param value [String, Integer, Float, Boolean, #read] The value to convert
+        # @return [String] The string representation of the value
+        def convert_to_content(value)
+          if value.respond_to?(:read)
+            value.read
+          else
+            value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/multipart/multipart_request.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Multipart
+      # @api private
+      class Request < Voltaria::Internal::Http::BaseRequest
+        attr_reader :body
+
+        # @param base_url [String] The base URL for the request
+        # @param path [String] The path for the request
+        # @param method [Symbol] 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 body [MultipartFormData, nil] The multipart form data for the request (optional)
+        # @param request_options [Voltaria::RequestOptions, Hash{Symbol=>Object}, nil]
+        def initialize(base_url:, path:, method:, headers: {}, query: {}, body: nil, request_options: {})
+          super(base_url:, path:, method:, headers:, query:, request_options:)
+
+          @body = body
+        end
+
+        # @return [Hash] The encoded HTTP request headers.
+        # @param protected_keys [Array<String>] Header keys set by the SDK client (e.g. auth, metadata)
+        #   that must not be overridden by additional_headers from request_options.
+        def encode_headers(protected_keys: [])
+          sdk_headers = {
+            "Content-Type" => @body.content_type
+          }.merge(@headers)
+          merge_additional_headers(sdk_headers, protected_keys:)
+        end
+
+        # @return [String, nil] The encoded HTTP request body.
+        def encode_body
+          @body&.encode
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/array.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      # An array of a specific type
+      class Array
+        include Voltaria::Internal::Types::Type
+
+        attr_reader :type
+
+        class << self
+          # Instantiates a new `Array` of a given type
+          #
+          # @param type [Object] The member type of this array
+          #
+          # @return [Voltaria::Internal::Types::Array]
+          def [](type)
+            new(type)
+          end
+        end
+
+        # @api private
+        def initialize(type)
+          @type = type
+        end
+
+        # Coerces a value into this array
+        #
+        # @param value [Object]
+        # @option strict [Boolean]
+        # @return [::Array]
+        def coerce(value, strict: strict?)
+          unless value.is_a?(::Array)
+            raise Errors::TypeError, "cannot coerce `#{value.class}` to Array<#{type}>" if strict
+
+            return value
+          end
+
+          value.map do |element|
+            Utils.coerce(type, element, strict: strict)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/boolean.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      module Boolean
+        extend Voltaria::Internal::Types::Union
+
+        member TrueClass
+        member FalseClass
+
+        # Overrides the base coercion method for enums to allow integer and string values to become booleans
+        #
+        # @param value [Object]
+        # @option strict [Boolean]
+        # @return [Object]
+        def self.coerce(value, strict: strict?)
+          case value
+          when TrueClass, FalseClass
+            return value
+          when Integer
+            return value == 1
+          when String
+            return %w[1 true].include?(value)
+          end
+
+          raise Errors::TypeError, "cannot coerce `#{value.class}` to Boolean" if strict
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/enum.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      # Module for defining enums
+      module Enum
+        include Type
+
+        # @api private
+        #
+        # @return [Array<Object>]
+        def values
+          @values ||= constants.map { |c| const_get(c) }
+        end
+
+        # @api private
+        def finalize!
+          values
+        end
+
+        # @api private
+        def strict?
+          @strict ||= false
+        end
+
+        # @api private
+        def strict!
+          @strict = true
+        end
+
+        def coerce(value, strict: strict?)
+          coerced_value = Utils.coerce(Symbol, value)
+
+          return coerced_value if values.include?(coerced_value)
+
+          raise Errors::TypeError, "`#{value}` not in enum #{self}" if strict
+
+          value
+        end
+
+        # Parse JSON string and coerce to the enum value
+        #
+        # @param str [String] JSON string to parse
+        # @return [String] The enum value
+        def load(str)
+          coerce(::JSON.parse(str))
+        end
+
+        def inspect
+          "#{name}[#{values.join(", ")}]"
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/hash.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      class Hash
+        include Type
+
+        attr_reader :key_type, :value_type
+
+        class << self
+          def [](key_type, value_type)
+            new(key_type, value_type)
+          end
+        end
+
+        def initialize(key_type, value_type)
+          @key_type = key_type
+          @value_type = value_type
+        end
+
+        def coerce(value, strict: strict?)
+          unless value.is_a?(::Hash)
+            raise Errors::TypeError, "not hash" if strict
+
+            return value
+          end
+
+          value.to_h do |k, v|
+            [Utils.coerce(key_type, k, strict: strict), Utils.coerce(value_type, v, strict: strict)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/model/field.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      class Model
+        # Definition of a field on a model
+        class Field
+          SENSITIVE_FIELD_NAMES = %i[
+            password secret token api_key apikey access_token refresh_token
+            client_secret client_id credential bearer authorization
+          ].freeze
+
+          attr_reader :name, :type, :optional, :nullable, :api_name, :value, :default
+
+          def initialize(name:, type:, optional: false, nullable: false, api_name: nil, value: nil, default: nil)
+            @name = name.to_sym
+            @type = type
+            @optional = optional
+            @nullable = nullable
+            @api_name = api_name || name.to_s
+            @value = value
+            @default = default
+          end
+
+          def literal?
+            !value.nil?
+          end
+
+          def sensitive?
+            SENSITIVE_FIELD_NAMES.include?(@name) ||
+              SENSITIVE_FIELD_NAMES.any? { |sensitive| @name.to_s.include?(sensitive.to_s) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/model.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      # @abstract
+      #
+      # An abstract model that all data objects will inherit from
+      class Model
+        include Type
+
+        class << self
+          # The defined fields for this model
+          #
+          # @api private
+          #
+          # @return [Hash<Symbol, Field>]
+          def fields
+            @fields ||= if self < Voltaria::Internal::Types::Model
+                          superclass.fields.dup
+                        else
+                          {}
+                        end
+          end
+
+          # Any extra fields that have been created from instantiation
+          #
+          # @api private
+          #
+          # @return [Hash<Symbol, Field>]
+          def extra_fields
+            @extra_fields ||= {}
+          end
+
+          # Define a new field on this model
+          #
+          # @param name [Symbol] The name of the field
+          # @param type [Class] Type of the field
+          # @option optional [Boolean] If it is an optional field
+          # @option nullable [Boolean] If it is a nullable field
+          # @option api_name [Symbol, String] Name in the API of this field. When serializing/deserializing, will use
+          #   this field name
+          # @return [void]
+          def field(name, type, optional: false, nullable: false, api_name: nil, default: nil)
+            add_field_definition(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
+                                 default: default)
+
+            define_accessor(name)
+            define_setter(name)
+          end
+
+          # Define a new literal for this model
+          #
+          # @param name [Symbol]
+          # @param value [Object]
+          # @option api_name [Symbol, String]
+          # @return [void]
+          def literal(name, value, api_name: nil)
+            add_field_definition(name: name, type: value.class, optional: false, nullable: false, api_name: api_name,
+                                 value: value)
+
+            define_accessor(name)
+          end
+
+          # Adds a new field definition into the class's fields registry
+          #
+          # @api private
+          #
+          # @param name [Symbol]
+          # @param type [Class]
+          # @option optional [Boolean]
+          # @return [void]
+          private def add_field_definition(name:, type:, optional:, nullable:, api_name:, default: nil, value: nil)
+            fields[name.to_sym] =
+              Field.new(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
+                        value: value, default: default)
+          end
+
+          # Adds a new field definition into the class's extra fields registry
+          #
+          # @api private
+          #
+          # @param name [Symbol]
+          # @param type [Class]
+          # @option required [Boolean]
+          # @option optional [Boolean]
+          # @return [void]
+          def add_extra_field_definition(name:, type:)
+            return if extra_fields.key?(name.to_sym)
+
+            extra_fields[name.to_sym] = Field.new(name: name, type: type, optional: true, nullable: false)
+
+            define_accessor(name)
+            define_setter(name)
+          end
+
+          # @api private
+          private def define_accessor(name)
+            method_name = name.to_sym
+
+            define_method(method_name) do
+              @data[name]
+            end
+          end
+
+          # @api private
+          private def define_setter(name)
+            method_name = :"#{name}="
+
+            define_method(method_name) do |val|
+              @data[name] = val
+            end
+          end
+
+          def coerce(value, strict: (respond_to?(:strict?) ? strict? : false)) # rubocop:disable Lint/UnusedMethodArgument
+            return value if value.is_a?(self)
+
+            return value unless value.is_a?(::Hash)
+
+            new(value)
+          end
+
+          def load(str)
+            coerce(::JSON.parse(str, symbolize_names: true))
+          end
+
+          def ===(instance)
+            instance.class.ancestors.include?(self)
+          end
+        end
+
+        # Creates a new instance of this model
+        # TODO: Should all this logic be in `#coerce` instead?
+        #
+        # @param values [Hash]
+        # @option strict [Boolean]
+        # @return [self]
+        def initialize(values = {})
+          @data = {}
+
+          values = Utils.symbolize_keys(values.dup)
+
+          self.class.fields.each do |field_name, field|
+            value = values.delete(field.api_name.to_sym) || values.delete(field.api_name) || values.delete(field_name)
+
+            field_value = value || (if field.literal?
+                                      field.value
+                                    elsif field.default
+                                      field.default
+                                    end)
+
+            @data[field_name] = Utils.coerce(field.type, field_value)
+          end
+
+          # Any remaining values in the input become extra fields
+          values.each do |name, value|
+            self.class.add_extra_field_definition(name: name, type: value.class)
+
+            @data[name.to_sym] = value
+          end
+        end
+
+        def to_h
+          result = self.class.fields.merge(self.class.extra_fields).each_with_object({}) do |(name, field), acc|
+            # If there is a value present in the data, use that value
+            # If there is a `nil` value present in the data, and it is optional but NOT nullable, exclude key altogether
+            # If there is a `nil` value present in the data, and it is optional and nullable, use the nil value
+
+            value = @data[name]
+
+            next if value.nil? && field.optional && !field.nullable
+
+            if value.is_a?(::Array)
+              value = value.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
+            elsif value.respond_to?(:to_h)
+              value = value.to_h
+            end
+
+            acc[field.api_name] = value
+          end
+
+          # Inject union discriminant if this instance was coerced from a discriminated union
+          # and the discriminant key is not already present in the result
+          discriminant_key = instance_variable_get(:@_fern_union_discriminant_key)
+          discriminant_value = instance_variable_get(:@_fern_union_discriminant_value)
+          result[discriminant_key] = discriminant_value if discriminant_key && discriminant_value && !result.key?(discriminant_key)
+
+          result
+        end
+
+        def ==(other)
+          self.class == other.class && to_h == other.to_h
+        end
+
+        # @return [String]
+        def inspect
+          attrs = @data.map do |name, value|
+            field = self.class.fields[name] || self.class.extra_fields[name]
+            display_value = field&.sensitive? ? "[REDACTED]" : value.inspect
+            "#{name}=#{display_value}"
+          end
+
+          "#<#{self.class.name}:0x#{object_id&.to_s(16)} #{attrs.join(" ")}>"
+        end
+      end
+    end
+  end
+end

data/lib/voltaria/internal/types/type.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Voltaria
+  module Internal
+    module Types
+      # @abstract
+      module Type
+        include Voltaria::Internal::JSON::Serializable
+
+        # Coerces a value to this type
+        #
+        # @param value [unknown]
+        # @option strict [Boolean] If we should strictly coerce this value
+        def coerce(value, strict: strict?)
+          raise NotImplementedError
+        end
+
+        # Returns if strictness is on for this type, defaults to `false`
+        #
+        # @return [Boolean]
+        def strict?
+          @strict ||= false
+        end
+
+        # Enable strictness by default for this type
+        #
+        # @return [void]
+        def strict!
+          @strict = true
+          self
+        end
+      end
+    end
+  end
+end