apiwork 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dffa2da3925e765760fc1b380f2f5fdb48ed0d055a4d6bfe87055b81577183ef
-  data.tar.gz: 85995c7465a4875da8ebc72ef04606b198667b8344c9f4717da3465fe5d06f19
+  metadata.gz: ef169b6db5b913f078945dbf9b29939139cd80d5d77e07c0339e9df070dfb259
+  data.tar.gz: b979dc9b7b721f5949952a22572fa8ea99593f59f1c5161a91fc8757b28205d5
 SHA512:
-  metadata.gz: 7d71c49e6cb7d238d5adb40c0a7b829536bdfa4cee09cd4993542906cec0aa6f861115a1e4dafcb7f4523a91be06aeffa02e1643d7b71a483b7b0cb5a9b6775b
-  data.tar.gz: e61222b9596f21de4a8af7cf1279db74a5db1c426fbd5f10affc083ce30d4c6f0da205105cec0355c2704830aad8574804dbb635f75582b5463b3391be455d9f
+  metadata.gz: 46548e8a016ade99fecc507ac9cb7d575b21278d4981e2ea5ebed9ddbdb81b2ff270669c4acca0f0cd6ce5e7437c9b14f62d51eff650492160e136f950a040fe
+  data.tar.gz: 8aabaa2bd3d750d425429ba4f47d034a07c1562c3ca5f90405d2c1d17e1f159d499e64bd906667bf9f6fe7dd3ee0640863dcb797a264ba985fcee6753f74925b

data/README.md

@@ -1,5 +1,13 @@
 # Apiwork
 
+[![Gem Version](https://img.shields.io/gem/v/apiwork)](https://rubygems.org/gems/apiwork)
+[![CI](https://github.com/skiftle/apiwork/actions/workflows/ci.yml/badge.svg)](https://github.com/skiftle/apiwork/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+![OpenAPI](https://img.shields.io/badge/OpenAPI-exports-6BA539?logo=openapiinitiative&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-exports-3178C6?logo=typescript&logoColor=white)
+![Zod](https://img.shields.io/badge/Zod-exports-3068B7?logo=zod&logoColor=white)
+
 Typed APIs for Rails.
 
 Apiwork lets you define your API once and derive validation, serialization, querying, and typed exports from the same definition.

data/lib/apiwork/adapter/base.rb

@@ -270,15 +270,17 @@ module Apiwork
         else
           build_custom_action_response(contract_class, representation_class, action, contract_action)
         end
+
+        build_request_query_type(contract_class, action.name, contract_action)
+        build_request_body_type(contract_class, action.name, contract_action)
       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)
+        build_response_body_type(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
@@ -286,12 +288,11 @@ module Apiwork
       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)
+        build_response_body_type(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
@@ -308,23 +309,51 @@ module Apiwork
         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
+      def build_response_body_type(contract_class, representation_class, action_name, response_type)
+        type_name = [action_name, 'response_body'].join('_').to_sym
+        return if contract_class.type?(type_name)
 
-        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)
+        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
+        contract_class.object(type_name) do |object|
+          shape_class.apply(object, representation_class.root_key, capabilities, representation_class, response_type, data_type:)
+        end
+      end
+
+      def build_request_query_type(contract_class, action_name, contract_action)
+        request = contract_action.request
+        return unless request.query.params.any?
+
+        type_name = [action_name, 'request_query'].join('_').to_sym
+        return if contract_class.type?(type_name)
+
+        contract_class.object(type_name) do |object|
+          request.query.params.each { |name, param| object.param(name, **normalize_request_param(param)) }
         end
+      end
+
+      def build_request_body_type(contract_class, action_name, contract_action)
+        request = contract_action.request
+        return unless request.body.params.any?
+
+        type_name = [action_name, 'request_body'].join('_').to_sym
+        return if contract_class.type?(type_name)
+
+        contract_class.object(type_name) do |object|
+          request.body.params.each { |name, param| object.param(name, **normalize_request_param(param)) }
+        end
+      end
 
-        { error_type: :error_response_body, success_type: contract_class.scoped_type_name(success_type_name) }
+      def normalize_request_param(param)
+        options = param.except(:name, :custom_type, :union, :partial)
+        options[:type] = param[:custom_type] if param[:custom_type]
+        options[:shape] = param[:union] if param[:union]
+        options
       end
 
       def resolve_resource_data_type(representation_class)

data/lib/apiwork/contract/action/response.rb

@@ -11,13 +11,10 @@ module Apiwork
         attr_reader :action_name,
                     :contract_class
 
-        attr_accessor :result_wrapper
-
         def initialize(contract_class, action_name)
           @contract_class = contract_class
           @action_name = action_name
           @body = nil
-          @result_wrapper = nil
           @no_content = false
         end
 

data/lib/apiwork/export/open_api.rb

@@ -203,39 +203,18 @@ module Apiwork
         if response.no_content?
           responses[:'204'] = { description: 'No content' }
         elsif response.body
-          body = response.body
-
-          if body.union? && body.discriminator.nil?
-            success_variant = body.variants[0]
-            error_variant = body.variants[1]
-
-            responses[:'200'] = {
-              content: {
-                'application/json': {
-                  schema: map_param(success_variant),
-                },
-              },
-              description: 'Successful response',
-            }
-
-            raises.each do |code|
-              error_code = api.error_codes[code]
-              responses[error_code.status.to_s.to_sym] = build_union_error_response(error_code.description, error_variant)
-            end
-          else
-            responses[:'200'] = {
-              content: {
-                'application/json': {
-                  schema: map_param(body),
-                },
+          responses[:'200'] = {
+            content: {
+              'application/json': {
+                schema: map_param(response.body),
               },
-              description: 'Successful response',
-            }
+            },
+            description: 'Successful response',
+          }
 
-            raises.each do |code|
-              error_code = api.error_codes[code]
-              responses[error_code.status.to_s.to_sym] = build_error_response(error_code.description)
-            end
+          raises.each do |code|
+            error_code = api.error_codes[code]
+            responses[error_code.status.to_s.to_sym] = build_error_response(error_code.description)
           end
         elsif response
           responses[:'200'] = {
@@ -280,17 +259,6 @@ module Apiwork
         }
       end
 
-      def build_union_error_response(description, error_variant)
-        {
-          description:,
-          content: {
-            'application/json': {
-              schema: map_param(error_variant),
-            },
-          },
-        }
-      end
-
       def surface
         @surface ||= SurfaceResolver.resolve(api)
       end

data/lib/apiwork/export/type_script_mapper.rb

@@ -116,18 +116,25 @@ module Apiwork
         "export type #{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)} = #{map_param(response_body_definition)};"
       end
 
-      def build_action_response_type(resource_name, action_name, response, parent_identifiers: [])
-        "export interface #{action_type_name(
-          resource_name,
-          action_name,
-          'Response',
-          parent_identifiers:,
-        )} {\n  body: #{action_type_name(
-          resource_name,
-          action_name,
-          'ResponseBody',
-          parent_identifiers:,
-        )};\n}"
+      def build_action_response_type(resource_name, action_name, response, parent_identifiers: [], raises:)
+        type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
+
+        success_variant = if response.no_content?
+                            '{ status: 204 }'
+                          else
+                            body_ref = action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)
+                            "{ status: 200; body: #{body_ref} }"
+                          end
+
+        error_statuses = resolve_error_statuses(raises)
+
+        if error_statuses.empty?
+          "export type #{type_name} = #{success_variant};"
+        else
+          error_variants = error_statuses.map { |status| "{ status: #{status}; body: #{pascal_case(:error_response_body)} }" }
+          all_variants = ([success_variant] + error_variants).map { |variant| "  | #{variant}" }.join("\n")
+          "export type #{type_name} =\n#{all_variants};"
+        end
       end
 
       def action_type_name(resource_name, action_name, suffix, parent_identifiers: [])
@@ -253,6 +260,10 @@ module Apiwork
 
       private
 
+      def resolve_error_statuses(raises)
+        raises.map { |code| @export.api.error_codes[code].status }.uniq.sort
+      end
+
       def build_enum_types(surface)
         surface.enums.map do |name, enum|
           { code: build_enum_type(name, enum), name: pascal_case(name) }
@@ -276,7 +287,7 @@ module Apiwork
 
           resource.actions.each do |action_name, action|
             types.concat(build_request_types(resource_name, action_name, action.request, parent_identifiers:))
-            types.concat(build_response_types(resource_name, action_name, action.response, parent_identifiers:))
+            types.concat(build_response_types(resource_name, action_name, action, parent_identifiers:))
           end
         end
 
@@ -306,22 +317,20 @@ module Apiwork
         types
       end
 
-      def build_response_types(resource_name, action_name, response, parent_identifiers:)
+      def build_response_types(resource_name, action_name, action, parent_identifiers:)
         types = []
+        response = action.response
 
-        if response.no_content?
-          type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
-          types << { code: "export type #{type_name} = never;", name: type_name }
-        elsif response.body?
+        if response.body?
           type_name = action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)
           code = build_action_response_body_type(resource_name, action_name, response.body, parent_identifiers:)
           types << { code:, name: type_name }
-
-          type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
-          code = build_action_response_type(resource_name, action_name, { body: response.body }, parent_identifiers:)
-          types << { code:, name: type_name }
         end
 
+        type_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
+        code = build_action_response_type(resource_name, action_name, response, parent_identifiers:, raises: action.raises)
+        types << { code:, name: type_name }
+
         types
       end
 

data/lib/apiwork/export/zod_mapper.rb

@@ -153,18 +153,27 @@ module Apiwork
         "export const #{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)}Schema = #{map_param(response_body)};"
       end
 
-      def build_action_response_schema(resource_name, action_name, response, parent_identifiers: [])
-        "export const #{action_type_name(
-          resource_name,
-          action_name,
-          'Response',
-          parent_identifiers:,
-        )}Schema = z.object({\n  body: #{action_type_name(
-          resource_name,
-          action_name,
-          'ResponseBody',
-          parent_identifiers:,
-        )}Schema\n});"
+      def build_action_response_schema(resource_name, action_name, response, parent_identifiers: [], raises:)
+        schema_name = action_type_name(resource_name, action_name, 'Response', parent_identifiers:)
+
+        success_variant = if response.no_content?
+                            'z.object({ status: z.literal(204) })'
+                          else
+                            body_ref = "#{action_type_name(resource_name, action_name, 'ResponseBody', parent_identifiers:)}Schema"
+                            "z.object({ status: z.literal(200), body: #{body_ref} })"
+                          end
+
+        error_statuses = resolve_error_statuses(raises)
+
+        if error_statuses.empty?
+          "export const #{schema_name}Schema = #{success_variant};"
+        else
+          error_variants = error_statuses.map do |status|
+            "z.object({ status: z.literal(#{status}), body: #{pascal_case(:error_response_body)}Schema })"
+          end
+          all_variants = ([success_variant] + error_variants).map { |variant| "  #{variant}" }.join(",\n")
+          "export const #{schema_name}Schema = z.discriminatedUnion('status', [\n#{all_variants}\n]);"
+        end
       end
 
       def action_type_name(resource_name, action_name, suffix, parent_identifiers: [])
@@ -367,12 +376,9 @@ module Apiwork
             end
 
             response = action.response
-            if response.no_content?
-              schemas << "export const #{action_type_name(resource_name, action_name, 'Response', parent_identifiers:)}Schema = z.never();"
-            elsif response.body?
-              schemas << build_action_response_body_schema(resource_name, action_name, response.body, parent_identifiers:)
-              schemas << build_action_response_schema(resource_name, action_name, { body: response.body }, parent_identifiers:)
-            end
+            schemas << build_action_response_body_schema(resource_name, action_name, response.body, parent_identifiers:) if response.body?
+
+            schemas << build_action_response_schema(resource_name, action_name, response, parent_identifiers:, raises: action.raises)
           end
         end
 
@@ -399,6 +405,10 @@ module Apiwork
         referenced_type.shape.key?(discriminator)
       end
 
+      def resolve_error_statuses(raises)
+        raises.map { |code| @export.api.error_codes[code].status }.uniq.sort
+      end
+
       def resolve_enum_schema(param)
         return nil unless param.scalar? && param.enum?
 

data/lib/apiwork/introspection/dump/action.rb

@@ -56,7 +56,7 @@ module Apiwork
           body_shape = response.body
           return { body: {}, no_content: false } unless body_shape
 
-          { body: Param.new(body_shape, result_wrapper: response.result_wrapper).to_h, no_content: false }
+          { body: Param.new(body_shape).to_h, no_content: false }
         end
 
         def raises

data/lib/apiwork/introspection/dump/param.rb

@@ -4,9 +4,8 @@ module Apiwork
   module Introspection
     module Dump
       class Param
-        def initialize(contract_param, result_wrapper: nil, visited: Set.new)
+        def initialize(contract_param, visited: Set.new)
           @contract_param = contract_param
-          @result_wrapper = result_wrapper
           @visited = visited
           @import_prefix_cache = {}
         end
@@ -14,8 +13,6 @@ module Apiwork
         def to_h
           return nil unless @contract_param
 
-          return build_result_wrapped if @result_wrapper
-
           result = {}
 
           @contract_param.params.sort_by { |name, _options| name.to_s }.each do |name, param_options|
@@ -31,38 +28,6 @@ module Apiwork
 
         private
 
-        def build_result_wrapped
-          success_type = @result_wrapper[:success_type]
-          error_type = @result_wrapper[:error_type]
-
-          success_variant = if success_type
-                              { reference: success_type, type: :reference }
-                            else
-                              { reference: nil, shape: build_success_params, type: :object }
-                            end
-
-          error_variant = if error_type
-                            { reference: error_type, type: :reference }
-                          else
-                            { reference: nil, shape: {}, type: :object }
-                          end
-
-          {
-            type: :union,
-            variants: [success_variant, error_variant],
-          }
-        end
-
-        def build_success_params
-          success_params = {}
-          @contract_param.params.sort_by { |name, _options| name.to_s }.each do |name, param_options|
-            dumped = build_param(name, param_options)
-            dumped[:optional] = true if param_options[:optional]
-            success_params[name] = dumped
-          end
-          success_params
-        end
-
         def build_param(name, options)
           return build_union_param(options) if options[:type] == :union
           return build_custom_type_param(options) if options[:custom_type]

data/lib/apiwork/reference_generator.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'yard'
 require 'fileutils'
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/object/blank'
@@ -22,6 +21,8 @@ module Apiwork
     end
 
     def generate
+      require 'yard'
+
       parse_source
       modules = extract_modules
       write_files(modules)
@@ -237,6 +238,7 @@ module Apiwork
       @modules = modules
       @modules_with_children = build_modules_with_children(modules)
 
+      write_root_index
       modules.each.with_index(1) do |mod, order|
         filepath = module_filepath(mod[:path])
         FileUtils.mkdir_p(File.dirname(filepath))
@@ -247,6 +249,22 @@ module Apiwork
       write_namespace_indexes
     end
 
+    def write_root_index
+      children = find_direct_children('Apiwork')
+      parts = []
+      parts << "---\norder: 2\n---\n"
+      parts << "# Reference\n"
+      parts << "Complete API reference for Apiwork's public classes.\n"
+
+      if children.any?
+        parts << "## Modules\n"
+        render_child_links(parts, 'Apiwork', children)
+      end
+
+      FileUtils.mkdir_p(OUTPUT_DIR)
+      File.write(File.join(OUTPUT_DIR, 'index.md'), parts.join("\n"))
+    end
+
     def write_namespace_indexes
       collect_all_folder_paths.each do |folder_parts|
         folder_path = File.join(OUTPUT_DIR, *folder_parts.map { |p| dasherize(p) })
@@ -337,8 +355,6 @@ module Apiwork
 
     def cleanup_old_files
       Dir.glob(File.join(OUTPUT_DIR, '**/*')).each do |entry|
-        next if entry == File.join(OUTPUT_DIR, 'index.md')
-
         FileUtils.rm_rf(entry)
       end
     end

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -122,7 +122,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description:
+description: Define your API once — and generate everything from it
 email:
 executables: []
 extensions: []
@@ -330,7 +330,9 @@ homepage: https://apiwork.dev
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/skiftle/apiwork/issues
   changelog_uri: https://github.com/skiftle/apiwork/blob/main/CHANGELOG.md
+  documentation_uri: https://apiwork.dev/guide/introduction
   homepage_uri: https://apiwork.dev
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/skiftle/apiwork
@@ -352,5 +354,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: The craft of API design
+summary: Typed APIs for Rails
 test_files: []