apiwork 0.0.0.pre → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fef277bf01c26fedb2244ef9380c0bca12473d89a237de282b6c2968cee46469
-  data.tar.gz: 4f68775b3061032af69de441b9d653c4f23f3e35075e9e6ca31a0139fd7f2fe8
+  metadata.gz: dffa2da3925e765760fc1b380f2f5fdb48ed0d055a4d6bfe87055b81577183ef
+  data.tar.gz: 85995c7465a4875da8ebc72ef04606b198667b8344c9f4717da3465fe5d06f19
 SHA512:
-  metadata.gz: ee34e78a369b305b726d8254abb692c04c4867e9e7ce8ad86e107674b4ff8dbb3fe63ccace7e30d738a1bf2fe56975208d14010f4c7930b64ee769191e397187
-  data.tar.gz: f6da4511ef0111b3994b452f49b151924c3a870adadf9e84618ef6913141aa3dd42fc03a672e4af443a5716adfcc10224c7d3fa1eddbbd42a0ac4952986541fa
+  metadata.gz: 7d71c49e6cb7d238d5adb40c0a7b829536bdfa4cee09cd4993542906cec0aa6f861115a1e4dafcb7f4523a91be06aeffa02e1643d7b71a483b7b0cb5a9b6775b
+  data.tar.gz: e61222b9596f21de4a8af7cf1279db74a5db1c426fbd5f10affc083ce30d4c6f0da205105cec0355c2704830aad8574804dbb635f75582b5463b3391be455d9f

data/LICENSE.txt

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+Copyright (c) 2026 skiftle
 
-Copyright (c) 2025 joauh
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1 +1,117 @@
-Coming soon!
+# Apiwork
+
+Typed APIs for Rails.
+
+Apiwork lets you define your API once and derive validation, serialization, querying, and typed exports from the same definition.
+
+It integrates with Rails rather than replacing it. Controllers, ActiveRecord models, and application logic remain unchanged.
+
+See https://apiwork.dev for full documentation.
+
+---
+
+## Overview
+
+Apiwork introduces an explicit, typed boundary to a Rails application.
+
+From a single definition, it provides:
+
+- Runtime request validation
+- Response serialization
+- Filtering, sorting, and pagination
+- Nested writes
+- OpenAPI specification
+- Generated TypeScript and Zod types
+
+The same structures that validate requests in production are used to generate client artifacts. There is no parallel schema layer.
+
+---
+
+## Example
+
+A representation describes how a model appears through the API:
+
+```ruby
+class InvoiceRepresentation < Apiwork::Representation::Base
+  attribute :id
+  attribute :number, writable: true, filterable: true, sortable: true
+  attribute :status, filterable: true
+  attribute :issued_on, writable: true, sortable: true
+
+  belongs_to :customer, filterable: true
+  has_many :lines, writable: true
+end
+```
+
+Types and nullability are inferred from ActiveRecord metadata.
+
+From this definition, Apiwork derives:
+
+- Typed request contracts
+- Response serializers
+- Query parameters for filtering and sorting
+- Offset or cursor-based pagination
+- Nested write handling
+- OpenAPI and client type exports
+
+A minimal controller:
+
+```ruby
+def index
+  expose Invoice.all
+end
+
+def create
+  expose Invoice.create(contract.body[:invoice])
+end
+```
+
+`contract.body` contains validated parameters.  
+`expose` serializes the response according to the representation.
+
+---
+
+## Querying
+
+Filtering and sorting are declared on attributes and associations.
+
+Example query parameters:
+
+```
+?filter[status][eq]=sent
+?sort[issued_on]=desc
+```
+
+Operators are typed and validated. Generated client types reflect the same structure.
+
+---
+
+## Standalone Contracts
+
+Representations are optional. Contracts can be defined independently of ActiveRecord for webhooks, external APIs, or custom request and response shapes.
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```bash
+bundle add apiwork
+```
+
+Then run:
+
+```bash
+rails generate apiwork:install
+```
+
+---
+
+## Status
+
+Under active development.
+
+## License
+
+MIT

data/Rakefile

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rubocop/rake_task"
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+require 'rspec/core/rake_task'
 
 RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
 
-task default: :rubocop
+task default: %i[rubocop spec]

data/app/controllers/apiwork/errors_controller.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class ErrorsController < ActionController::API
+    include Controller
+
+    skip_contract_validation!
+
+    def not_found
+      expose_error :not_found
+    end
+  end
+end

data/app/controllers/apiwork/exports_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class ExportsController < ActionController::API
+    def show
+      api_class = API.find!(params[:api_base_path])
+      export_name = params[:export_name].to_sym
+      export_class = Export.find!(export_name)
+
+      raw_options = { key_format: api_class.key_format }
+        .merge(api_class.export_configs[export_name].to_h)
+        .merge(params.to_unsafe_h.symbolize_keys)
+
+      format = raw_options[:format]&.to_sym
+      options = export_class.extract_options(raw_options)
+
+      result = Export.generate(export_name, api_class.base_path, format:, **options)
+
+      render content_type: export_class.content_type_for(format:), plain: result
+    end
+  end
+end

data/lib/apiwork/abstractable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Abstractable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_abstract, default: false, instance_predicate: false
+    end
+
+    class_methods do
+      def abstract!
+        self._abstract = true
+      end
+
+      def abstract?
+        _abstract
+      end
+
+      def inherited(subclass)
+        super
+        subclass._abstract = false
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/base.rb

@@ -0,0 +1,369 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    # @api public
+    # Base class for adapters.
+    #
+    # The engine of an API. Handles both introspection (generating types from
+    # representations) and runtime (processing requests through capabilities,
+    # serializing, and wrapping responses). The class declaration acts as a manifest.
+    #
+    # @example
+    #   class MyAdapter < Apiwork::Adapter::Base
+    #     adapter_name :my
+    #
+    #     resource_serializer Serializer::Resource::Default
+    #     error_serializer Serializer::Error::Default
+    #
+    #     member_wrapper Wrapper::Member::Default
+    #     collection_wrapper Wrapper::Collection::Default
+    #     error_wrapper Wrapper::Error::Default
+    #
+    #     capability Capability::Filtering
+    #     capability Capability::Pagination
+    #   end
+    class Base
+      include Configurable
+
+      class << self
+        # @api public
+        # The adapter name for this adapter.
+        #
+        # @param value [Symbol, String, nil] (nil)
+        #   The adapter name.
+        # @return [Symbol, nil]
+        #
+        # @example
+        #   adapter_name :my
+        def adapter_name(value = nil)
+          @adapter_name = value.to_sym if value
+          @adapter_name
+        end
+
+        # @api public
+        # Registers a capability for this adapter.
+        #
+        # Capabilities are self-contained concerns (pagination, filtering, etc.)
+        # that handle both introspection and runtime behavior.
+        #
+        # @param klass [Class<Capability::Base>]
+        #   The capability class.
+        # @return [void]
+        #
+        # @example
+        #   capability Capability::Filtering
+        #   capability Capability::Pagination
+        def capability(klass)
+          @capabilities ||= []
+          @capabilities << klass
+
+          return unless klass.options.any?
+
+          name = klass.capability_name
+          options[name] = Configuration::Option.new(name, :hash, children: klass.options)
+        end
+
+        # @api public
+        # Skips an inherited capability by name.
+        #
+        # @param name [Symbol]
+        #   The capability name to skip.
+        # @return [void]
+        #
+        # @example
+        #   skip_capability :pagination
+        def skip_capability(name)
+          @skipped_capabilities ||= []
+          @skipped_capabilities << name.to_sym
+        end
+
+        def capabilities
+          inherited = superclass.respond_to?(:capabilities) ? superclass.capabilities : []
+          skipped = @skipped_capabilities || []
+          all = (inherited + (@capabilities || [])).uniq
+          all.reject { |capability| skipped.include?(capability.capability_name) }
+        end
+
+        # @api public
+        # Sets the serializer class for records and collections.
+        #
+        # @param klass [Class<Serializer::Resource::Base>, nil] (nil)
+        #   The serializer class.
+        # @return [Class<Serializer::Resource::Base>, nil]
+        #
+        # @example
+        #   resource_serializer Serializer::Resource::Default
+        def resource_serializer(klass = nil)
+          if klass
+            validate_class_setter!(:resource_serializer, klass, Serializer::Resource::Base, 'Serializer')
+            @resource_serializer = klass
+          end
+          @resource_serializer || (superclass.respond_to?(:resource_serializer) && superclass.resource_serializer)
+        end
+
+        # @api public
+        # Sets the serializer class for errors.
+        #
+        # @param klass [Class<Serializer::Error::Base>, nil] (nil)
+        #   The serializer class.
+        # @return [Class<Serializer::Error::Base>, nil]
+        #
+        # @example
+        #   error_serializer Serializer::Error::Default
+        def error_serializer(klass = nil)
+          if klass
+            validate_class_setter!(:error_serializer, klass, Serializer::Error::Base, 'Serializer')
+            @error_serializer = klass
+          end
+          @error_serializer || (superclass.respond_to?(:error_serializer) && superclass.error_serializer)
+        end
+
+        # @api public
+        # Sets the wrapper class for single-record responses.
+        #
+        # @param klass [Class<Wrapper::Member::Base>, nil] (nil)
+        #   The wrapper class.
+        # @return [Class<Wrapper::Member::Base>, nil]
+        #
+        # @example
+        #   member_wrapper Wrapper::Member::Default
+        def member_wrapper(klass = nil)
+          if klass
+            validate_class_setter!(:member_wrapper, klass, Wrapper::Member::Base, 'Wrapper')
+            @member_wrapper = klass
+          end
+          @member_wrapper || (superclass.respond_to?(:member_wrapper) && superclass.member_wrapper)
+        end
+
+        # @api public
+        # Sets the wrapper class for collection responses.
+        #
+        # @param klass [Class<Wrapper::Collection::Base>, nil] (nil)
+        #   The wrapper class.
+        # @return [Class<Wrapper::Collection::Base>, nil]
+        #
+        # @example
+        #   collection_wrapper Wrapper::Collection::Default
+        def collection_wrapper(klass = nil)
+          if klass
+            validate_class_setter!(:collection_wrapper, klass, Wrapper::Collection::Base, 'Wrapper')
+            @collection_wrapper = klass
+          end
+          @collection_wrapper || (superclass.respond_to?(:collection_wrapper) && superclass.collection_wrapper)
+        end
+
+        # @api public
+        # Sets the wrapper class for error responses.
+        #
+        # @param klass [Class<Wrapper::Error::Base>, nil] (nil)
+        #   The wrapper class.
+        # @return [Class<Wrapper::Error::Base>, nil]
+        #
+        # @example
+        #   error_wrapper Wrapper::Error::Default
+        def error_wrapper(klass = nil)
+          if klass
+            validate_class_setter!(:error_wrapper, klass, Wrapper::Error::Base, 'Wrapper')
+            @error_wrapper = klass
+          end
+          @error_wrapper || (superclass.respond_to?(:error_wrapper) && superclass.error_wrapper)
+        end
+
+        private
+
+        def validate_class_setter!(name, klass, base_class, label)
+          unless klass.is_a?(Class)
+            raise ConfigurationError,
+                  "#{name} must be a #{label} class, got #{klass.class}. " \
+                  "Use: #{name} Example (not 'Example' or :example)"
+          end
+          return if klass < base_class
+
+          raise ConfigurationError,
+                "#{name} must be a #{label} class (subclass of #{base_class.name}), " \
+                "got #{klass}"
+        end
+      end
+
+      def process_collection(collection, representation_class, request, context: {}, meta: {})
+        collection, metadata, serialize_options = apply_capabilities(collection, representation_class, request, wrapper_type: :collection)
+        data = self.class.resource_serializer.serialize(representation_class, collection, context:, serialize_options:)
+        self.class.collection_wrapper.wrap(data, metadata, representation_class.root_key, meta)
+      end
+
+      def process_member(record, representation_class, request, context: {}, meta: {})
+        record, metadata, serialize_options = apply_capabilities(record, representation_class, request, wrapper_type: :member)
+        data = self.class.resource_serializer.serialize(representation_class, record, context:, serialize_options:)
+        self.class.member_wrapper.wrap(data, metadata, representation_class.root_key, meta)
+      end
+
+      def process_error(error, representation_class, context: {})
+        data = self.class.error_serializer.serialize(error, context:)
+        self.class.error_wrapper.wrap(data)
+      end
+
+      def register_api(api_class)
+        capabilities.each do |capability|
+          capability.api_types(api_class)
+        end
+
+        error_serializer_class = self.class.error_serializer
+        error_serializer_class.new.api_types(api_class)
+
+        build_error_response_body(api_class, error_serializer_class)
+      end
+
+      def register_contract(contract_class, representation_class, actions)
+        capabilities.each do |capability|
+          capability.contract_types(contract_class, representation_class, actions)
+        end
+
+        self.class.resource_serializer.new(representation_class).contract_types(contract_class)
+
+        build_action_responses(contract_class, representation_class, actions)
+      end
+
+      def apply_request_transformers(request, phase:)
+        run_capability_request_transformers(request, phase:)
+      end
+
+      def apply_response_transformers(response)
+        run_capability_response_transformers(response)
+      end
+
+      def capabilities
+        @capabilities ||= self.class.capabilities.map do |klass|
+          klass.new({}, adapter_name: self.class.adapter_name)
+        end
+      end
+
+      private
+
+      def apply_capabilities(data, representation_class, request, wrapper_type:)
+        Capability::Runner.run(
+          capabilities,
+          data:,
+          representation_class:,
+          request:,
+          wrapper_type:,
+        )
+      end
+
+      def build_action_responses(contract_class, representation_class, actions)
+        actions.each_value do |action|
+          build_action_response(contract_class, representation_class, action)
+        end
+      end
+
+      def build_action_response(contract_class, representation_class, action)
+        contract_action = contract_class.action(action.name)
+        return if contract_action.resets_response?
+
+        case action.name
+        when :index
+          build_collection_action_response(contract_class, representation_class, action, contract_action)
+        when :show, :create, :update
+          build_member_action_response(contract_class, representation_class, action, contract_action)
+        when :destroy
+          contract_action.response { no_content! }
+        else
+          build_custom_action_response(contract_class, representation_class, action, contract_action)
+        end
+      end
+
+      def build_member_action_response(contract_class, representation_class, action, contract_action)
+        result_wrapper = build_result_wrapper(contract_class, representation_class, action.name, :member)
+        member_shape_class = self.class.member_wrapper.shape_class
+        data_type = resolve_resource_data_type(representation_class)
+
+        contract_action.response do |response|
+          response.result_wrapper = result_wrapper
+          response.body do |body|
+            member_shape_class.apply(body, representation_class.root_key, capabilities, representation_class, :member, data_type:)
+          end
+        end
+      end
+
+      def build_collection_action_response(contract_class, representation_class, action, contract_action)
+        result_wrapper = build_result_wrapper(contract_class, representation_class, action.name, :collection)
+        collection_shape_class = self.class.collection_wrapper.shape_class
+        data_type = resolve_resource_data_type(representation_class)
+
+        contract_action.response do |response|
+          response.result_wrapper = result_wrapper
+          response.body do |body|
+            collection_shape_class.apply(body, representation_class.root_key, capabilities, representation_class, :collection, data_type:)
+          end
+        end
+      end
+
+      def build_custom_action_response(contract_class, representation_class, action, contract_action)
+        if action.method == :delete
+          contract_action.response { no_content! }
+        elsif action.collection?
+          build_collection_action_response(contract_class, representation_class, action, contract_action)
+        elsif action.member?
+          build_member_action_response(contract_class, representation_class, action, contract_action)
+        end
+      end
+
+      def build_result_wrapper(contract_class, representation_class, action_name, response_type)
+        success_type_name = [action_name, 'success_response_body'].join('_').to_sym
+
+        unless contract_class.type?(success_type_name)
+          shape_class = if response_type == :collection
+                          self.class.collection_wrapper.shape_class
+                        else
+                          self.class.member_wrapper.shape_class
+                        end
+          data_type = resolve_resource_data_type(representation_class)
+
+          contract_class.object(success_type_name) do |object|
+            shape_class.apply(object, representation_class.root_key, capabilities, representation_class, response_type, data_type:)
+          end
+        end
+
+        { error_type: :error_response_body, success_type: contract_class.scoped_type_name(success_type_name) }
+      end
+
+      def resolve_resource_data_type(representation_class)
+        self.class.resource_serializer.data_type.call(representation_class)
+      end
+
+      def build_error_response_body(api_class, error_serializer_class)
+        return if api_class.type?(:error_response_body)
+
+        shape_class = self.class.error_wrapper.shape_class
+        return unless shape_class
+
+        data_type = error_serializer_class.data_type
+
+        api_class.object(:error_response_body) do |object|
+          shape_class.apply(object, nil, [], nil, :error, data_type:)
+        end
+      end
+
+      def run_capability_request_transformers(request, phase:)
+        transformers = capability_request_transformers.select { |transformer_class| transformer_class.phase == phase }
+        result = request
+        transformers.each { |transformer_class| result = transformer_class.transform(result) }
+        result
+      end
+
+      def run_capability_response_transformers(response)
+        result = response
+        capability_response_transformers.each { |transformer_class| result = transformer_class.transform(result) }
+        result
+      end
+
+      def capability_request_transformers
+        self.class.capabilities.flat_map(&:request_transformers)
+      end
+
+      def capability_response_transformers
+        self.class.capabilities.flat_map(&:response_transformers)
+      end
+    end
+  end
+end

data/lib/apiwork/adapter/builder/api/base.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Adapter
+    module Builder
+      module API
+        # @api public
+        # Base class for API-phase type builders.
+        #
+        # API phase runs once per API at initialization time.
+        # Use it to register shared types used across all contracts.
+        #
+        # @example
+        #   module Builder
+        #     class API < Adapter::Builder::API::Base
+        #       def build
+        #         enum(:status, values: %w[active inactive])
+        #         object(:error) do |object|
+        #           object.string(:message)
+        #         end
+        #       end
+        #     end
+        #   end
+        class Base
+          attr_reader :data_type
+
+          # @!method enum(name, values:, **options, &block)
+          #   @api public
+          #   @see API::Base#enum
+          # @!method enum?(name)
+          #   @api public
+          #   @see API::Base#enum?
+          # @!method object(name, **options, &block)
+          #   @api public
+          #   @see API::Base#object
+          # @!method type?(name)
+          #   @api public
+          #   @see API::Base#type?
+          # @!method union(name, **options, &block)
+          #   @api public
+          #   @see API::Base#union
+          delegate :enum,
+                   :enum?,
+                   :object,
+                   :type?,
+                   :union,
+                   to: :@api_class
+
+          def initialize(api_class, data_type: nil)
+            @api_class = api_class
+            @data_type = data_type
+          end
+
+          # @api public
+          # Builds API-level types.
+          #
+          # Override this method to register shared types.
+          # @return [void]
+          def build
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end