apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/contract/base.rb

@@ -0,0 +1,714 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Contract
+    # @api public
+    # Base class for contracts.
+    #
+    # Validates requests and defines response shapes. Drives type generation and
+    # request parsing. Types are defined manually per action or auto-generated
+    # from a linked representation.
+    #
+    # @example Manual contract
+    #   class InvoiceContract < Apiwork::Contract::Base
+    #     action :create do
+    #       request do
+    #         body do
+    #           string :title
+    #           decimal :amount, min: 0
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @example With representation
+    #   class InvoiceContract < Apiwork::Contract::Base
+    #     representation InvoiceRepresentation
+    #   end
+    #
+    # @!scope class
+    # @!method abstract!
+    #   @api public
+    #   Marks this contract as abstract.
+    #
+    #   Abstract contracts serve as base classes for other contracts.
+    #   Use this when creating application-wide base contracts that define
+    #   shared imports or configuration. Subclasses automatically become non-abstract.
+    #   @return [void]
+    #   @example Application base contract
+    #     class ApplicationContract < Apiwork::Contract::Base
+    #       abstract!
+    #     end
+    #
+    # @!method abstract?
+    #   @api public
+    #   Whether this contract is abstract.
+    #   @return [Boolean]
+    class Base
+      include Abstractable
+
+      # @!attribute [r] issues
+      #   @api public
+      #   The issues for this contract.
+      #   @return [Array<Issue>]
+      attr_reader :action_name,
+                  :issues,
+                  :request
+
+      # @!method body
+      #   @api public
+      #   The body for this contract.
+      #
+      #   Use this in controller actions to access validated request data.
+      #   Contains type-coerced values matching your contract definition.
+      #   Invalid requests are rejected before the action runs.
+      #
+      #   @return [Hash]
+      #
+      #   @example
+      #     def create
+      #       Invoice.create!(contract.body[:invoice])
+      #     end
+      #
+      # @!method query
+      #   @api public
+      #   The query for this contract.
+      #
+      #   Use this in controller actions to access validated request data.
+      #   Contains type-coerced values matching your contract definition.
+      #   Invalid requests are rejected before the action runs.
+      #
+      #   @return [Hash]
+      #
+      #   @example
+      #     def index
+      #       Invoice.where(status: contract.query[:status])
+      #     end
+      delegate :body,
+               :query,
+               to: :request
+
+      class << self
+        # @api public
+        # The representation class for this contract.
+        #
+        # @return [Class<Representation::Base>, nil]
+        # @see .representation
+        attr_reader :representation_class
+
+        # @api public
+        # Prefixes types, enums, and unions in introspection output.
+        #
+        # Must be unique within the API. Derived from the contract class
+        # name when not set (e.g., `RecurringInvoiceContract` becomes
+        # `recurring_invoice`).
+        #
+        # @param value [Symbol, String, nil] (nil)
+        #   The identifier prefix.
+        # @return [String, nil]
+        #
+        # @example
+        #   class InvoiceContract < Apiwork::Contract::Base
+        #     identifier :billing
+        #
+        #     object :address do
+        #       string :street
+        #     end
+        #     # In introspection: :address becomes :billing_address
+        #   end
+        def identifier(value = nil)
+          return @identifier if value.nil?
+
+          @identifier = value.to_s
+        end
+
+        # @api public
+        # Configures the representation class for this contract.
+        #
+        # Adapters use the representation to auto-generate request/response
+        # types. Use {.representation_class} to retrieve.
+        #
+        # @param klass [Class<Representation::Base>]
+        #   The representation class.
+        # @return [void]
+        # @raise [ArgumentError] if klass is not a Representation subclass
+        #
+        # @example
+        #   class InvoiceContract < Apiwork::Contract::Base
+        #     representation InvoiceRepresentation
+        #   end
+        def representation(klass)
+          unless klass.is_a?(Class)
+            raise ConfigurationError,
+                  "representation must be a Representation class, got #{klass.class}. " \
+                  "Use: representation InvoiceRepresentation (not 'InvoiceRepresentation' or :invoice)"
+          end
+          unless klass < Representation::Base
+            raise ConfigurationError,
+                  'representation must be a Representation class (subclass of Apiwork::Representation::Base), ' \
+                  "got #{klass}"
+          end
+
+          @representation_class = klass
+        end
+
+        # @api public
+        # Defines or extends an object type for this contract.
+        #
+        # Subclasses inherit parent types. In introspection, types are prefixed with the
+        # contract's {.identifier} (e.g., `:item` in `InvoiceContract` becomes `:invoice_item`).
+        #
+        # Multiple calls with the same name merge fields (declaration merging).
+        #
+        # @param name [Symbol]
+        #   The object name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param example [Object, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @yieldparam object [API::Object]
+        # @return [void]
+        #
+        # @example Define and reference
+        #   object :item do
+        #     string :description
+        #     decimal :amount
+        #   end
+        #
+        #   action :create do
+        #     request do
+        #       body do
+        #         array :items do
+        #           reference :item
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @example Different shapes for request and response
+        #   object :invoice do
+        #     uuid :id
+        #     string :number
+        #     string :status
+        #   end
+        #
+        #   object :invoice_payload do
+        #     string :number
+        #     string :status
+        #   end
+        #
+        #   action :create do
+        #     request do
+        #       body do
+        #         reference :invoice, to: :invoice_payload
+        #       end
+        #     end
+        #     response do
+        #       body do
+        #         reference :invoice
+        #       end
+        #     end
+        #   end
+        def object(
+          name,
+          deprecated: false,
+          description: nil,
+          example: nil,
+          &block
+        )
+          api_class.register_object(
+            name,
+            deprecated:,
+            description:,
+            example:,
+            scope: self,
+            &block
+          )
+        end
+
+        # @api public
+        # Defines a fragment type for this contract.
+        #
+        # Fragments are only available for merging into other types and never appear as standalone types. Use
+        # fragments to define reusable field groups.
+        #
+        # @param name [Symbol]
+        #   The fragment name.
+        # @yieldparam object [API::Object]
+        # @return [void]
+        #
+        # @example Reusable timestamps
+        #   fragment :timestamps do
+        #     datetime :created_at
+        #     datetime :updated_at
+        #   end
+        #
+        #   object :invoice do
+        #     merge :timestamps
+        #     string :number
+        #   end
+        def fragment(name, &block)
+          api_class.register_fragment(name, scope: self, &block)
+        end
+
+        # @api public
+        # Defines or extends an enum for this contract.
+        #
+        # Subclasses inherit parent enums. In introspection, enums are prefixed with the
+        # contract's {.identifier} (e.g., `:status` in `InvoiceContract` becomes `:invoice_status`).
+        #
+        # Multiple calls with the same name merge values (declaration merging).
+        #
+        # @param name [Symbol]
+        #   The enum name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param example [String, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @param values [Array<String>, nil] (nil)
+        #   The allowed values.
+        # @return [void]
+        #
+        # @example Define and reference
+        #   enum :status, values: %w[draft sent paid]
+        #
+        #   action :update do
+        #     request do
+        #       body do
+        #         string :status, enum: :status
+        #       end
+        #     end
+        #   end
+        #
+        # @example Inline values (without separate definition)
+        #   action :index do
+        #     request do
+        #       query do
+        #         string? :priority, enum: %w[low medium high]
+        #       end
+        #     end
+        #   end
+        def enum(
+          name,
+          deprecated: false,
+          description: nil,
+          example: nil,
+          values: nil
+        )
+          api_class.register_enum(
+            name,
+            deprecated:,
+            description:,
+            example:,
+            values:,
+            scope: self,
+          )
+        end
+
+        # @api public
+        # Defines or extends a discriminated union for this contract.
+        #
+        # Subclasses inherit parent unions. In introspection, unions are prefixed with the
+        # contract's {.identifier} (e.g., `:payment_method` in `InvoiceContract` becomes `:invoice_payment_method`).
+        #
+        # Multiple calls with the same name merge variants (declaration merging).
+        #
+        # @param name [Symbol]
+        #   The union name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param discriminator [Symbol, nil] (nil)
+        #   The discriminator field name.
+        # @param example [Object, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @yieldparam union [API::Union]
+        # @return [void]
+        #
+        # @example Define and reference
+        #   union :payment_method, discriminator: :type do
+        #     variant tag: 'card' do
+        #       object do
+        #         string :last_four
+        #       end
+        #     end
+        #     variant tag: 'bank_transfer' do
+        #       object do
+        #         string :bank_name
+        #         string :account_number
+        #       end
+        #     end
+        #   end
+        #
+        #   action :create do
+        #     request do
+        #       body do
+        #         reference :payment_method
+        #       end
+        #     end
+        #   end
+        def union(
+          name,
+          deprecated: false,
+          description: nil,
+          discriminator: nil,
+          example: nil,
+          &block
+        )
+          api_class.register_union(
+            name,
+            deprecated:,
+            description:,
+            discriminator:,
+            example:,
+            scope: self,
+            &block
+          )
+        end
+
+        # @api public
+        # Imports types from another contract for reuse.
+        #
+        # Imported types are accessed with a prefix matching the alias.
+        #
+        # @param klass [Class<Contract::Base>]
+        #   The contract class to import types from.
+        # @param as [Symbol]
+        #   The alias prefix.
+        # @return [void]
+        # @raise [ArgumentError] if klass is not a Contract subclass
+        # @raise [ArgumentError] if as is not a Symbol
+        #
+        # @example
+        #   import UserContract, as: :user
+        #   # UserContract's :address becomes :user_address
+        def import(klass, as:)
+          unless klass.is_a?(Class)
+            raise ConfigurationError,
+                  "import must be a Class constant, got #{klass.class}. " \
+                                                   "Use: import UserContract, as: :user (not 'UserContract' or :user_contract)"
+          end
+
+          unless klass < Contract::Base
+            raise ConfigurationError,
+                  'import must be a Contract class (subclass of Apiwork::Contract::Base), ' \
+                                                   "got #{klass}"
+          end
+
+          unless as.is_a?(Symbol)
+            raise ConfigurationError,
+                  "import alias must be a Symbol, got #{as.class}. " \
+                                                   'Use: import UserContract, as: :user'
+          end
+
+          imports[as] = klass
+
+          return if klass.building?
+          return unless klass.representation? && klass.api_class
+
+          klass.building = true
+          begin
+            klass.api_class.ensure_contract_built!(klass)
+          ensure
+            klass.building = false
+          end
+        end
+
+        # @api public
+        # Defines or extends an action on this contract.
+        #
+        # Multiple calls with the same name merge definitions (declaration merging).
+        #
+        # @param name [Symbol]
+        #   The action name. Matches your controller action.
+        # @param replace [Boolean] (false)
+        #   Whether to discard any existing definition and start fresh. Use when overriding
+        #   auto-generated actions from representation.
+        # @yieldparam action [Contract::Action]
+        # @return [Contract::Action]
+        #
+        # @example Query parameters
+        #   action :index do
+        #     request do
+        #       query do
+        #         string? :search
+        #         integer? :page
+        #       end
+        #     end
+        #   end
+        #
+        # @example Request body with custom type
+        #   action :create do
+        #     request do
+        #       body do
+        #         reference :invoice, to: :invoice_payload
+        #       end
+        #     end
+        #     response do
+        #       body do
+        #         reference :invoice
+        #       end
+        #     end
+        #   end
+        #
+        # @example Override auto-generated action
+        #   action :destroy, replace: true do
+        #     response do
+        #       body do
+        #         reference :invoice
+        #       end
+        #     end
+        #   end
+        #
+        # @example No content response
+        #   action :destroy do
+        #     response { no_content! }
+        #   end
+        def action(name, replace: false, &block)
+          name = name.to_sym
+
+          action = if replace
+                     Action.new(self, name, replace: true)
+                   else
+                     actions[name] ||= Action.new(self, name)
+                   end
+
+          if block_given?
+            block.arity.positive? ? yield(action) : action.instance_eval(&block)
+          end
+          actions[name] = action
+        end
+
+        # @api public
+        # Returns introspection data for this contract.
+        #
+        # @param expand [Boolean] (false)
+        #   Whether to expand all types inline.
+        # @param locale [Symbol, nil] (nil)
+        #   The locale for translations.
+        # @return [Introspection::Contract]
+        #
+        # @example
+        #   InvoiceContract.introspect
+        def introspect(expand: false, locale: nil)
+          api_class.introspect_contract(self, expand:, locale:)
+        end
+
+        attr_writer :building
+
+        def actions
+          @actions ||= {}
+        end
+
+        def imports
+          @imports ||= {}
+        end
+
+        def building?
+          @building
+        end
+
+        def synthetic_contracts
+          @synthetic_contracts ||= {}
+        end
+
+        def synthetic?
+          @synthetic == true
+        end
+
+        def contract_for(representation_class)
+          return nil unless representation_class&.name
+
+          contract_name = representation_class.name.sub(/Representation\z/, 'Contract')
+          contract_class = contract_name.safe_constantize
+
+          return contract_class if contract_class.is_a?(Class) && contract_class < Contract::Base
+
+          synthetic_contracts[representation_class] ||= build_synthetic_contract(representation_class, api_class)
+        end
+
+        def build_synthetic_contract(representation_class, api_class)
+          Class.new(Contract::Base) do
+            @synthetic = true
+            @representation_class = representation_class
+            @api_class = api_class
+          end
+        end
+
+        def representation?
+          representation_class.present?
+        end
+
+        def scope_prefix
+          return @identifier if @identifier
+
+          if name
+            name
+              .demodulize
+              .delete_suffix('Contract')
+              .underscore
+          elsif representation_class
+            representation_class.name
+              .demodulize
+              .delete_suffix('Representation')
+              .underscore
+          end
+        end
+
+        def resolve_custom_type(type_name, visited: Set.new)
+          raise ConfigurationError, "Circular import detected while resolving :#{type_name}" if visited.include?(self)
+
+          if api_class
+            result = api_class.type_definition(type_name, scope: self)
+            return result if result
+          end
+
+          result = resolve_imported_type(type_name, visited: visited.dup.add(self))
+          return result if result
+
+          resolve_parent_type(type_name, visited: visited.dup.add(self))
+        end
+
+        def action_for(action_name)
+          api_class.ensure_contract_built!(self)
+
+          action_name = action_name.to_sym
+          actions[action_name]
+        end
+
+        def api_class
+          return @api_class if @api_class
+          return nil unless name
+
+          namespace = name.deconstantize
+          return nil if namespace.blank?
+
+          API.find("/#{namespace.underscore.tr('::', '/')}")
+        end
+
+        def parse_response(response, action)
+          ResponseParser.parse(self, action, response)
+        end
+
+        def type?(name)
+          resolve_custom_type(name).present?
+        end
+
+        def enum?(name)
+          enum_values(name).present?
+        end
+
+        def enum_values(enum_name, visited: Set.new)
+          return nil if visited.include?(self)
+
+          if api_class
+            result = api_class.enum_values(enum_name, scope: self)
+            return result if result
+          end
+
+          result = resolve_imported_enum_values(enum_name, visited: visited.dup.add(self))
+          return result if result
+
+          resolve_parent_enum_values(enum_name, visited: visited.dup.add(self))
+        end
+
+        def scoped_type_name(name)
+          api_class.scoped_type_name(self, name)
+        end
+
+        def scoped_enum_name(name)
+          api_class.scoped_enum_name(self, name)
+        end
+
+        private
+
+        def resolve_imported_type(type_name, visited:)
+          type_string = type_name.to_s
+
+          imports.each do |import_alias, imported_contract|
+            prefix = "#{import_alias}_"
+            next unless type_string.start_with?(prefix)
+
+            unprefixed_name = type_string.delete_prefix(prefix).to_sym
+            result = imported_contract.resolve_custom_type(unprefixed_name, visited:)
+            return result if result
+          end
+
+          nil
+        end
+
+        def resolve_parent_type(type_name, visited:)
+          parent = superclass
+          return nil unless parent < Contract::Base
+
+          parent.resolve_custom_type(type_name, visited:)
+        end
+
+        def resolve_imported_enum_values(enum_name, visited:)
+          enum_string = enum_name.to_s
+
+          imports.each do |import_alias, imported_contract|
+            prefix = "#{import_alias}_"
+            next unless enum_string.start_with?(prefix)
+
+            unprefixed_name = enum_string.delete_prefix(prefix).to_sym
+            result = imported_contract.enum_values(unprefixed_name, visited:)
+            return result if result
+          end
+
+          nil
+        end
+
+        def resolve_parent_enum_values(enum_name, visited:)
+          parent = superclass
+          return nil unless parent < Contract::Base
+
+          parent.enum_values(enum_name, visited:)
+        end
+      end
+
+      def initialize(action_name, request, coerce: false)
+        request = normalize_request(request)
+        result = RequestParser.parse(self.class, action_name, request, coerce:)
+        @request = prepare_request(result.request)
+        @action_name = action_name.to_sym
+        @issues = result.issues
+      end
+
+      # @api public
+      # Whether this contract is valid.
+      #
+      # @return [Boolean]
+      def valid?
+        issues.empty?
+      end
+
+      # @api public
+      # Whether this contract is invalid.
+      #
+      # @return [Boolean]
+      def invalid?
+        issues.any?
+      end
+
+      private
+
+      def normalize_request(request)
+        api_class = self.class.api_class
+        result = api_class.normalize_request(request)
+        api_class.adapter.apply_request_transformers(result, phase: :before)
+      end
+
+      def prepare_request(request)
+        api_class = self.class.api_class
+        result = api_class.prepare_request(request)
+        api_class.adapter.apply_request_transformers(result, phase: :after)
+      end
+    end
+  end
+end