peal 0.2.0 → 0.3.0

data/lib/peal/internal/types/union.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Types
+      # Define a union between two types
+      module Union
+        include Peal::Internal::Types::Type
+
+        def members
+          @members ||= []
+        end
+
+        # Add a member to this union
+        #
+        # @param type [Object]
+        # @option key [Symbol, String]
+        # @return [void]
+        def member(type, key: nil)
+          members.push([key, Utils.wrap_type(type)])
+          self
+        end
+
+        def type_member?(type)
+          members.any? { |_key, type_fn| type == type_fn.call }
+        end
+
+        # Set the discriminant for this union
+        #
+        # @param key [Symbol, String]
+        # @return [void]
+        def discriminant(key)
+          @discriminant = key
+        end
+
+        # @api private
+        private def discriminated?
+          !@discriminant.nil?
+        end
+
+        # Check if value matches a type, handling type wrapper instances
+        # (Internal::Types::Hash and Internal::Types::Array instances)
+        #
+        # @param value [Object]
+        # @param member_type [Object]
+        # @return [Boolean]
+        private def type_matches?(value, member_type)
+          case member_type
+          when Peal::Internal::Types::Hash
+            value.is_a?(::Hash)
+          when Peal::Internal::Types::Array
+            value.is_a?(::Array)
+          when Class, Module
+            value.is_a?(member_type)
+          else
+            false
+          end
+        end
+
+        # Resolves the type of a value to be one of the members
+        #
+        # @param value [Object]
+        # @return [Class]
+        private def resolve_member(value)
+          if discriminated? && value.is_a?(::Hash)
+            # Try both symbol and string keys for the discriminant
+            discriminant_value = value.fetch(@discriminant, nil) || value.fetch(@discriminant.to_s, nil)
+
+            return if discriminant_value.nil?
+
+            # Convert to string for consistent comparison
+            discriminant_str = discriminant_value.to_s
+
+            # First try exact match
+            members_hash = members.to_h
+            result = members_hash[discriminant_str]&.call
+            return result if result
+
+            # Try case-insensitive match as fallback
+            discriminant_lower = discriminant_str.downcase
+            matching_keys = members_hash.keys.select { |k| k.to_s.downcase == discriminant_lower }
+
+            # Only use case-insensitive match if exactly one key matches (avoid ambiguity)
+            return members_hash[matching_keys.first]&.call if matching_keys.length == 1
+
+            nil
+          else
+            # First try exact type matching
+            result = members.find do |_key, mem|
+              member_type = Utils.unwrap_type(mem)
+              type_matches?(value, member_type)
+            end&.last&.call
+
+            return result if result
+
+            # For Hash values, try to coerce into Model member types
+            if value.is_a?(::Hash)
+              members.find do |_key, mem|
+                member_type = Utils.unwrap_type(mem)
+                # Check if member_type is a Model class
+                next unless member_type.is_a?(Class) && member_type <= Model
+
+                # Try to coerce the hash into this model type with strict mode
+                begin
+                  candidate = Utils.coerce(member_type, value, strict: true)
+
+                  # Validate that all required (non-optional) fields are present
+                  # This ensures undiscriminated unions properly distinguish between member types
+                  member_type.fields.each do |field_name, field|
+                    raise Errors::TypeError, "Required field `#{field_name}` missing for union member #{member_type.name}" if candidate.instance_variable_get(:@data)[field_name].nil? && !field.optional
+                  end
+
+                  true
+                rescue Errors::TypeError
+                  false
+                end
+              end&.last&.call
+            end
+          end
+        end
+
+        def coerce(value, strict: strict?)
+          type = resolve_member(value)
+
+          unless type
+            return value unless strict
+
+            if discriminated?
+              raise Errors::TypeError,
+                    "value of type `#{value.class}` not member of union #{self}"
+            end
+
+            raise Errors::TypeError, "could not resolve to member of union #{self}"
+          end
+
+          coerced = Utils.coerce(type, value, strict: strict)
+
+          # For discriminated unions, store the discriminant info on the coerced instance
+          # so it can be injected back during serialization (to_h)
+          if discriminated? && value.is_a?(::Hash) && coerced.is_a?(Model)
+            discriminant_value = value.fetch(@discriminant, nil) || value.fetch(@discriminant.to_s, nil)
+            if discriminant_value
+              coerced.instance_variable_set(:@_fern_union_discriminant_key, @discriminant.to_s)
+              coerced.instance_variable_set(:@_fern_union_discriminant_value, discriminant_value)
+            end
+          end
+
+          coerced
+        end
+
+        # Parse JSON string and coerce to the correct union member type
+        #
+        # @param str [String] JSON string to parse
+        # @return [Object] Coerced value matching a union member
+        def load(str)
+          coerce(::JSON.parse(str, symbolize_names: true))
+        end
+      end
+    end
+  end
+end

data/lib/peal/internal/types/unknown.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Types
+      module Unknown
+        include Peal::Internal::Types::Type
+
+        def coerce(value)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/peal/internal/types/utils.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Peal
+  module Internal
+    module Types
+      # Utilities for dealing with and checking types
+      module Utils
+        # Wraps a type into a type function
+        #
+        # @param type [Proc, Object]
+        # @return [Proc]
+        def self.wrap_type(type)
+          case type
+          when Proc
+            type
+          else
+            -> { type }
+          end
+        end
+
+        # Resolves a type or type function into a type
+        #
+        # @param type [Proc, Object]
+        # @return [Object]
+        def self.unwrap_type(type)
+          type.is_a?(Proc) ? type.call : type
+        end
+
+        EXACT_SCALAR_TYPES = [String, Integer, Float].freeze
+        private_constant :EXACT_SCALAR_TYPES
+
+        def self.coerce(target, value, strict: false)
+          type = unwrap_type(target)
+
+          # Fast path: exact String/Integer/Float instances are returned as-is, as the branches below would.
+          # Subclasses still go through their `to_s`/`to_i`/`to_f` conversion.
+          return value if EXACT_SCALAR_TYPES.include?(type) && value.instance_of?(type)
+
+          case type
+          in Array
+            case value
+            when ::Array
+              return type.coerce(value, strict: strict)
+            when Set, ::Hash
+              return coerce(type, value.to_a)
+            end
+          in Hash
+            case value
+            when ::Hash
+              return type.coerce(value, strict: strict)
+            when ::Array
+              return coerce(type, value.to_h)
+            end
+          in Class if type <= NilClass
+            return nil
+          in Class if type <= String
+            case value
+            when String, Symbol, Numeric, TrueClass, FalseClass
+              return value.to_s
+            end
+          in Class if type <= Symbol
+            case value
+            when Symbol, String
+              return value.to_sym
+            end
+          in Class if type <= Integer
+            case value
+            when Numeric, String, Time
+              return value.to_i
+            when Symbol
+              # JSON object keys are parsed as symbols, so numeric map keys arrive as e.g. :"1"
+              parsed = Integer(value.to_s, 10, exception: false)
+              return parsed unless parsed.nil?
+            end
+          in Class if type <= Float
+            case value
+            when Numeric, Time, String
+              return value.to_f
+            when Symbol
+              parsed = Float(value.to_s, exception: false)
+              return parsed unless parsed.nil?
+            end
+          in Class if type <= Model
+            case value
+            when type
+              return value
+            when ::Hash
+              return type.coerce(value, strict: strict)
+            end
+          in Module
+            case type
+            in Enum | Union
+              return type.coerce(value, strict: strict)
+            else
+              value # rubocop:disable Lint/Void
+            end
+          else
+            value # rubocop:disable Lint/Void
+          end
+
+          raise Errors::TypeError, "cannot coerce value of type `#{value.class}` to `#{target}`" if strict
+
+          value
+        end
+
+        def self.symbolize_keys(hash)
+          hash.transform_keys(&:to_sym)
+        end
+
+        # Converts camelCase keys to snake_case symbols
+        # This allows SDK methods to accept both snake_case and camelCase keys
+        # e.g., { refundMethod: ... } becomes { refund_method: ... }
+        #
+        # @param hash [Hash]
+        # @return [Hash]
+        def self.normalize_keys(hash)
+          hash.transform_keys do |key|
+            key_str = key.to_s
+            # Convert camelCase to snake_case
+            snake_case = key_str.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+            snake_case.to_sym
+          end
+        end
+
+        # Converts Time values (including ActiveSupport::TimeWithZone), recursively within hashes and arrays, to
+        # RFC 3339 strings with millisecond precision. `Time#to_s` (e.g. "2026-10-16 01:40:16 UTC") is not RFC 3339.
+        # Date and DateTime values are left unchanged because their `to_s` output is already ISO 8601.
+        #
+        # @param value [Object]
+        # @return [Object]
+        def self.serialize_times(value)
+          case value
+          when ::Hash
+            value.transform_values { |item| serialize_times(item) }
+          when ::Array
+            value.map { |item| serialize_times(item) }
+          else
+            value.is_a?(::Time) ? value.iso8601(3) : value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/peal/invitations/client.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Peal
+  module Invitations
+    class Client
+      # @param client [Peal::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Lists the workspace's pending invitations, oldest first, expired ones included. Needs invitation:create, as an
+      # invitation's id opens its link, and a member rather than an API key; invitations to the owner role are listed to
+      # owners only.
+      #
+      # @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 [String] :workspace_id
+      #
+      # @example
+      #   client.invitations.list(workspace_id: "workspaceId")
+      #
+      # @return [Array[Peal::Types::Invitation]]
+      def list(request_options: {}, **params)
+        params = Peal::Internal::Types::Utils.normalize_keys(params)
+        request = Peal::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "GET",
+          path: "api/workspaces/#{URI.encode_uri_component(params[:workspace_id].to_s)}/invitations",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Peal::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Peal::Internal::Types::Utils.coerce(Internal::Types::Array[Peal::Types::Invitation], (response.body.to_s.empty? ? nil : JSON.parse(response.body, symbolize_names: true)))
+        else
+          error_class = Peal::Errors::ResponseError.subclass_for_code(code)
+          error_types = {
+            401 => Peal::Types::UnauthenticatedEncoded,
+            403 => Peal::Types::ForbiddenEncoded
+          }
+          error_body = Peal::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body, headers: response.to_hash)
+        end
+      end
+
+      # Invites someone to the workspace with a role: Peal emails them a link that works for 7 days, in their language
+      # when they have an account, in the inviter's otherwise. A pending invitation to the same address is revoked, and
+      # its link stops working. Only owners invite owners. On a server that bills, the members and the other pending
+      # invitations must leave room in the workspace's plan (PlanLimitReached). Needs invitation:create, and a member in
+      # person: not an API key, nor staff impersonating one.
+      #
+      # @param request_options [Hash]
+      # @param params [Peal::Invitations::Types::NewInvitation]
+      # @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 [String] :workspace_id
+      #
+      # @example
+      #   client.invitations.create(
+      #     workspace_id: "workspaceId",
+      #     email: "email",
+      #     role: "owner"
+      #   )
+      #
+      # @return [Peal::Types::Invitation]
+      def create(request_options: {}, **params)
+        params = Peal::Internal::Types::Utils.normalize_keys(params)
+        request_data = Peal::Invitations::Types::NewInvitation.new(params).to_h
+        non_body_param_names = %w[workspaceId]
+        body = request_data.except(*non_body_param_names)
+
+        request = Peal::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "api/workspaces/#{URI.encode_uri_component(params[:workspace_id].to_s)}/invitations",
+          body: body,
+          request_options: request_options,
+          max_retries: 0
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Peal::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          (response.body.to_s.empty? ? nil : Peal::Types::Invitation.load(response.body))
+        else
+          error_class = Peal::Errors::ResponseError.subclass_for_code(code)
+          error_types = {
+            401 => Peal::Types::UnauthenticatedEncoded,
+            402 => Peal::Types::PlanLimitReachedEncoded,
+            403 => Peal::Types::ForbiddenEncoded
+          }
+          error_body = Peal::Errors::ResponseError.load_error_body(code, response.body, error_types)
+          raise error_class.new(response.body, code: code, body: error_body, headers: response.to_hash)
+        end
+      end
+
+      # Revokes a pending invitation of the workspace: its link stops working at once. Needs invitation:cancel, and a
+      # member in person: not an API key, nor staff impersonating one.
+      #
+      # @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 [String] :workspace_id
+      # @option params [String] :invitation_id
+      #
+      # @example
+      #   client.invitations.revoke(
+      #     workspace_id: "workspaceId",
+      #     invitation_id: "invitationId"
+      #   )
+      #
+      # @return [untyped]
+      def revoke(request_options: {}, **params)
+        params = Peal::Internal::Types::Utils.normalize_keys(params)
+        request = Peal::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "DELETE",
+          path: "api/workspaces/#{URI.encode_uri_component(params[:workspace_id].to_s)}/invitations/#{URI.encode_uri_component(params[:invitation_id].to_s)}",
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Peal::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        return if code.between?(200, 299)
+
+        error_class = Peal::Errors::ResponseError.subclass_for_code(code)
+        error_types = {
+          401 => Peal::Types::UnauthenticatedEncoded,
+          403 => Peal::Types::ForbiddenEncoded
+        }
+        error_body = Peal::Errors::ResponseError.load_error_body(code, response.body, error_types)
+        raise error_class.new(response.body, code: code, body: error_body, headers: response.to_hash)
+      end
+    end
+  end
+end

data/lib/peal/invitations/types/list_invitations_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Peal
+  module Invitations
+    module Types
+      class ListInvitationsRequest < Internal::Types::Model
+        field :workspace_id, -> { String }, optional: false, nullable: false, api_name: "workspaceId"
+      end
+    end
+  end
+end

data/lib/peal/invitations/types/new_invitation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Peal
+  module Invitations
+    module Types
+      class NewInvitation < Internal::Types::Model
+        field :workspace_id, -> { String }, optional: false, nullable: false, api_name: "workspaceId"
+
+        field :email, -> { String }, optional: false, nullable: false
+
+        field :role, -> { Peal::Types::Role }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/peal/invitations/types/revoke_invitations_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Peal
+  module Invitations
+    module Types
+      class RevokeInvitationsRequest < Internal::Types::Model
+        field :workspace_id, -> { String }, optional: false, nullable: false, api_name: "workspaceId"
+
+        field :invitation_id, -> { String }, optional: false, nullable: false, api_name: "invitationId"
+      end
+    end
+  end
+end