apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/adapter/capability/operation/base.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module Operation
+        # @api public
+        # Base class for capability Operation phase.
+        #
+        # Operation phase runs on each request.
+        # Use it to transform data at runtime.
+        class Base
+          # @!attribute [r] data
+          #   @api public
+          #   The data for this operation.
+          #
+          #   @return [Object]
+          # @!attribute [r] options
+          #   @api public
+          #   The options for this operation.
+          #
+          #   @return [Configuration]
+          # @!attribute [r] request
+          #   @api public
+          #   The request for this operation.
+          #
+          #   @return [Request]
+          # @!attribute [r] representation_class
+          #   @api public
+          #   The representation class for this operation.
+          #
+          #   @return [Class<Representation::Base>]
+          attr_reader :data,
+                      :options,
+                      :representation_class,
+                      :request
+
+          class << self
+            # @api public
+            # The target for this operation.
+            #
+            # @param value [Symbol, nil] (nil) [:collection, :member]
+            #   The target type.
+            # @return [Symbol, nil]
+            def target(value = nil)
+              @target = value if value
+              @target
+            end
+
+            # @api public
+            # Defines metadata shape for this operation.
+            #
+            # Pass a block or a {MetadataShape} subclass.
+            # Blocks are evaluated via instance_exec, providing access to
+            # type DSL methods and capability options.
+            #
+            # @param klass [Class<MetadataShape>, nil] (nil)
+            #   The metadata shape class.
+            # @yield block that defines metadata structure
+            # @return [Class<MetadataShape>, nil]
+            #
+            # @example With block
+            #   metadata_shape do
+            #     reference(:pagination, to: :offset_pagination)
+            #   end
+            #
+            # @example With class
+            #   metadata_shape PaginationShape
+            def metadata_shape(klass = nil, &block)
+              if klass
+                @metadata_shape_class = klass
+              elsif block
+                @metadata_shape_class = wrap_metadata_shape_block(block)
+              end
+              @metadata_shape_class
+            end
+
+            private
+
+            def wrap_metadata_shape_block(callable)
+              Class.new(MetadataShape) do
+                define_singleton_method(:callable) { callable }
+
+                def apply
+                  block = self.class.callable
+                  block.arity.positive? ? block.call(self) : instance_exec(&block)
+                end
+              end
+            end
+          end
+
+          def initialize(data, representation_class, options, request, translation_context: {})
+            @data = data
+            @representation_class = representation_class
+            @options = options
+            @request = request
+            @translation_context = translation_context
+          end
+
+          # @api public
+          # Applies this operation to the data.
+          #
+          # Override this method to implement transformation logic.
+          # Return `nil` if no changes are made.
+          #
+          # @return [Result, nil]
+          def apply
+            raise NotImplementedError
+          end
+
+          # @api public
+          # Creates a result object.
+          #
+          # @param data [Object, nil] (nil)
+          #   The transformed data.
+          # @param includes [Array, nil] (nil)
+          #   The associations to preload.
+          # @param metadata [Hash, nil] (nil)
+          #   The metadata to add to response.
+          # @param serialize_options [Hash, nil] (nil)
+          #   The options for serialization.
+          # @return [Result]
+          def result(data: nil, includes: nil, metadata: nil, serialize_options: nil)
+            Result.new(
+              data:,
+              includes:,
+              metadata:,
+              serialize_options:,
+            )
+          end
+
+          # @api public
+          # Translates a key using the adapter's i18n convention.
+          #
+          # Lookup order:
+          # 1. `apiwork.apis.<locale_key>.adapters.<adapter_name>.capabilities.<capability_name>.<segments>`
+          # 2. `apiwork.adapters.<adapter_name>.capabilities.<capability_name>.<segments>`
+          # 3. Provided default
+          #
+          # @param segments [Array<Symbol, String>]
+          #   The key path segments.
+          # @param default [String, nil] (nil)
+          #   The fallback value if no translation found.
+          # @return [String, nil]
+          #
+          # @example
+          #   translate(:issues, :invalid, :detail)
+          #   # Tries: apiwork.apis.billing.adapters.standard.capabilities.writing.issues.invalid.detail
+          #   # Falls back to: apiwork.adapters.standard.capabilities.writing.issues.invalid.detail
+          def translate(*segments, default: nil)
+            adapter_name = @translation_context[:adapter_name]
+            capability_name = @translation_context[:capability_name]
+            locale_key = @translation_context[:locale_key]
+            key_suffix = segments.join('.')
+
+            if locale_key
+              api_key = :"apiwork.apis.#{locale_key}.adapters.#{adapter_name}.capabilities.#{capability_name}.#{key_suffix}"
+              result = I18n.translate(api_key, default: nil)
+              return result if result
+            end
+
+            adapter_key = :"apiwork.adapters.#{adapter_name}.capabilities.#{capability_name}.#{key_suffix}"
+            result = I18n.translate(adapter_key, default: nil)
+            return result if result
+
+            default
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/operation/metadata_shape.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module Operation
+        # @api public
+        # Shape builder for operation metadata.
+        #
+        # Provides {#options} for accessing capability configuration,
+        # plus all DSL methods from {API::Object} for defining structure.
+        # Used by operations to define their metadata contribution.
+        #
+        # @example Add pagination metadata shape
+        #   metadata_shape do
+        #     reference :pagination
+        #   end
+        class MetadataShape
+          class << self
+            def apply(object, options)
+              new(object, options).apply
+            end
+          end
+
+          # @api public
+          # The capability options for this metadata shape.
+          #
+          # @return [Configuration]
+          attr_reader :options
+
+          # @!method array(name, **options, &block)
+          #   @api public
+          #   @see API::Object#array
+          # @!method array?(name, **options, &block)
+          #   @api public
+          #   @see API::Object#array?
+          # @!method binary(name, **options)
+          #   @api public
+          #   @see API::Object#binary
+          # @!method binary?(name, **options)
+          #   @api public
+          #   @see API::Object#binary?
+          # @!method boolean(name, **options)
+          #   @api public
+          #   @see API::Object#boolean
+          # @!method boolean?(name, **options)
+          #   @api public
+          #   @see API::Object#boolean?
+          # @!method date(name, **options)
+          #   @api public
+          #   @see API::Object#date
+          # @!method date?(name, **options)
+          #   @api public
+          #   @see API::Object#date?
+          # @!method datetime(name, **options)
+          #   @api public
+          #   @see API::Object#datetime
+          # @!method datetime?(name, **options)
+          #   @api public
+          #   @see API::Object#datetime?
+          # @!method decimal(name, **options)
+          #   @api public
+          #   @see API::Object#decimal
+          # @!method decimal?(name, **options)
+          #   @api public
+          #   @see API::Object#decimal?
+          # @!method integer(name, **options)
+          #   @api public
+          #   @see API::Object#integer
+          # @!method integer?(name, **options)
+          #   @api public
+          #   @see API::Object#integer?
+          # @!method literal(name, value:, **options)
+          #   @api public
+          #   @see API::Object#literal
+          # @!method merge(other)
+          #   @api public
+          #   @see API::Object#merge
+          # @!method number(name, **options)
+          #   @api public
+          #   @see API::Object#number
+          # @!method number?(name, **options)
+          #   @api public
+          #   @see API::Object#number?
+          # @!method object(name, **options, &block)
+          #   @api public
+          #   @see API::Object#object
+          # @!method object?(name, **options, &block)
+          #   @api public
+          #   @see API::Object#object?
+          # @!method reference(name, **options)
+          #   @api public
+          #   @see API::Object#reference
+          # @!method reference?(name, **options)
+          #   @api public
+          #   @see API::Object#reference?
+          # @!method string(name, **options)
+          #   @api public
+          #   @see API::Object#string
+          # @!method string?(name, **options)
+          #   @api public
+          #   @see API::Object#string?
+          # @!method time(name, **options)
+          #   @api public
+          #   @see API::Object#time
+          # @!method time?(name, **options)
+          #   @api public
+          #   @see API::Object#time?
+          # @!method union(name, **options, &block)
+          #   @api public
+          #   @see API::Object#union
+          # @!method union?(name, **options, &block)
+          #   @api public
+          #   @see API::Object#union?
+          # @!method uuid(name, **options)
+          #   @api public
+          #   @see API::Object#uuid
+          # @!method uuid?(name, **options)
+          #   @api public
+          #   @see API::Object#uuid?
+          delegate :array,
+                   :array?,
+                   :binary,
+                   :binary?,
+                   :boolean,
+                   :boolean?,
+                   :date,
+                   :date?,
+                   :datetime,
+                   :datetime?,
+                   :decimal,
+                   :decimal?,
+                   :integer,
+                   :integer?,
+                   :literal,
+                   :merge,
+                   :number,
+                   :number?,
+                   :object,
+                   :object?,
+                   :reference,
+                   :reference?,
+                   :string,
+                   :string?,
+                   :time,
+                   :time?,
+                   :union,
+                   :union?,
+                   :uuid,
+                   :uuid?,
+                   to: :@object
+
+          def initialize(object, options)
+            @object = object
+            @options = options
+          end
+
+          def apply
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      class Result
+        attr_reader :data,
+                    :includes,
+                    :metadata,
+                    :serialize_options
+
+        def initialize(data:, includes: nil, metadata: nil, serialize_options: nil)
+          @data = data
+          @metadata = metadata
+          @includes = includes
+          @serialize_options = serialize_options
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/runner.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      class Runner
+        class << self
+          def run(capabilities, data:, representation_class:, request:, wrapper_type:)
+            new(capabilities, wrapper_type:).run(data, representation_class, request)
+          end
+        end
+
+        def initialize(capabilities, wrapper_type:)
+          @capabilities = capabilities
+          @wrapper_type = wrapper_type
+        end
+
+        def run(data, representation_class, request)
+          metadata = {}
+          serialize_options = {}
+          includes = []
+
+          result_data = @capabilities.reduce(data) do |current, capability|
+            result = capability.apply(current, representation_class, request, wrapper_type: @wrapper_type)
+            next current unless result
+
+            metadata.merge!(result.metadata) if result.metadata
+            serialize_options.merge!(result.serialize_options || {})
+            includes << result.includes if result.includes.present?
+            result.data || current
+          end
+
+          includes.concat(representation_class.preloads)
+          preloaded = preload_associations(result_data, includes.flatten.compact)
+
+          [preloaded, metadata, serialize_options]
+        end
+
+        private
+
+        def preload_associations(data, includes)
+          return data if includes.blank?
+
+          if data.is_a?(ActiveRecord::Relation)
+            data.includes(*includes)
+          elsif data.is_a?(ActiveRecord::Base)
+            ActiveRecord::Associations::Preloader.new(associations: includes, records: [data]).call
+            data
+          else
+            data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/transformer/request/base.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module Transformer
+        module Request
+          # @api public
+          # Base class for request transformers.
+          #
+          # Request transformers modify requests before or after validation.
+          # Register transformers in capabilities using {Capability::Base.request_transformer}.
+          #
+          # @see Standard::Capability::Filtering::RequestTransformer
+          # @see Standard::Capability::Writing::RequestTransformer
+          #
+          # @example Strip whitespace from strings
+          #   class MyRequestTransformer < Capability::Transformer::Request::Base
+          #     phase :before
+          #
+          #     def transform
+          #       request.transform { |data| strip_strings(data) }
+          #     end
+          #
+          #     private
+          #
+          #     def strip_strings(value)
+          #       case value
+          #       when String then value.strip
+          #       when Hash then value.transform_values { |v| strip_strings(v) }
+          #       when Array then value.map { |v| strip_strings(v) }
+          #       else value
+          #       end
+          #     end
+          #   end
+          class Base
+            attr_reader :request
+
+            class << self
+              # @api public
+              # The phase for this transformer.
+              #
+              # @param value [Symbol, nil] (nil) [:after, :before]
+              #   The phase. Defaults to `:before` when not set.
+              # @return [Symbol]
+              def phase(value = nil)
+                @phase = value if value
+                @phase || :before
+              end
+
+              def transform(request)
+                new(request).transform
+              end
+            end
+
+            def initialize(request)
+              @request = request
+            end
+
+            # @api public
+            # Transforms the request.
+            #
+            # @return [Request]
+            def transform
+              raise NotImplementedError
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/capability/transformer/response/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Capability
+      module Transformer
+        module Response
+          # @api public
+          # Base class for response transformers.
+          #
+          # Response transformers modify responses before they are returned.
+          # Register transformers in capabilities using {Capability::Base.response_transformer}.
+          #
+          # @example Add generated_at to response
+          #   class MyResponseTransformer < Capability::Transformer::Response::Base
+          #     def transform
+          #       response.transform_body { |body| body.merge(generated_at: Time.zone.now) }
+          #     end
+          #   end
+          class Base
+            attr_reader :response
+
+            class << self
+              def transform(response)
+                new(response).transform
+              end
+            end
+
+            def initialize(response)
+              @response = response
+            end
+
+            # @api public
+            # Transforms the response.
+            #
+            # @return [Response]
+            def transform
+              raise NotImplementedError
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/registry.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    class Registry < Apiwork::Registry
+      class << self
+        def register(adapter_class)
+          raise ArgumentError, 'Adapter must inherit from Apiwork::Adapter::Base' unless adapter_class < Base
+          raise ArgumentError, "Adapter #{adapter_class} must define an adapter_name" unless adapter_class.adapter_name
+
+          store[adapter_class.adapter_name] = adapter_class
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/serializer/error/base.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Serializer
+      module Error
+        # @api public
+        # Base class for error serializers.
+        #
+        # Error serializers handle serialization of errors and define
+        # error-related types at the API level.
+        #
+        # @example
+        #   class MyErrorSerializer < Serializer::Error::Base
+        #     api_builder Builder::API
+        #
+        #     def serialize(error, context:)
+        #       { errors: error.issues.map(&:to_h) }
+        #     end
+        #   end
+        class Base
+          class << self
+            def serialize(error, context:)
+              new.serialize(error, context:)
+            end
+
+            # @api public
+            # The data type for this serializer.
+            #
+            # @param name [Symbol, nil] (nil)
+            #   The type name.
+            # @return [Symbol, nil]
+            def data_type(name = nil)
+              @data_type = name if name
+              @data_type
+            end
+
+            # @api public
+            # The API builder for this serializer.
+            #
+            # @param klass [Class<Builder::API::Base>, nil] (nil)
+            #   The builder class.
+            # @return [Class<Builder::API::Base>, nil]
+            def api_builder(klass = nil)
+              @api_builder = klass if klass
+              @api_builder
+            end
+          end
+
+          def api_types(api_class)
+            builder_class = self.class.api_builder
+            return unless builder_class
+
+            builder_class.new(api_class, data_type: self.class.data_type).build
+          end
+
+          # @api public
+          # Serializes an error.
+          #
+          # @param error [Error]
+          #   The error to serialize.
+          # @param context [Hash]
+          #   The serialization context.
+          # @return [Hash]
+          def serialize(error, context:)
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/serializer/error/default/api_builder.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Serializer
+      module Error
+        class Default < Base
+          class APIBuilder < Adapter::Builder::API::Base
+            def build
+              enum(:layer, values: %w[http contract domain])
+
+              object(:issue) do |object|
+                object.string(:code)
+                object.string(:detail)
+                object.array(:path, &:string)
+                object.string(:pointer)
+                object.object(:meta)
+              end
+
+              object(data_type) do |object|
+                object.reference(:layer)
+                object.array(:issues) do |element|
+                  element.reference(:issue)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/serializer/error/default.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Serializer
+      module Error
+        # @api public
+        # Default error serializer.
+        #
+        # Serializes errors into a hash with issues array and layer.
+        #
+        # @example Configuration
+        #   class MyAdapter < Adapter::Base
+        #     error_serializer Serializer::Error::Default
+        #   end
+        #
+        # @example Output
+        #   {
+        #     "issues": [{ "code": "invalid", "detail": "...", "path": [...], "pointer": "/..." }],
+        #     "layer": "contract"
+        #   }
+        class Default < Base
+          data_type :error
+
+          api_builder APIBuilder
+
+          def serialize(error, context:)
+            {
+              issues: error.issues.map(&:to_h),
+              layer: error.layer,
+            }
+          end
+        end
+      end
+    end
+  end
+end