respondo-graphql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 479397a32c82bd347b77d8ae9a342abb4b3796a3a6e33919661313a4e7a172dd
+  data.tar.gz: 84492ab253009751ffc4f7ffd391cc79576a1af64330eebb54179f31612356f3
+SHA512:
+  metadata.gz: 6a967a00d8e92435ebb7f69cf82a43aced84acfe9aafc2a53f2e55c7fb4a447d9d0607d1d19cd091417aba22c67d92b391c4b49c05276bc74a308364b9087d85
+  data.tar.gz: '01168e9e5bc5fdb2de915ff285a70c428bc12910ac6d63b03dd91b47ce24319b5e94c6c82f42f31b1cb3b8ae6247ade373e2a91b977f95eb1a05c813ef88a20b'

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## [0.1.0] — Initial release
+
+First release of `respondo-graphql`, the GraphQL sibling of the `respondo` JSON
+gem. It is a standalone gem — no dependency on `respondo`.
+
+### Added
+- GraphQL-spec response envelope: `errors` (failures only), `data`, `extensions`.
+- 50 status-aware controller helpers with the same names and signatures as
+  `respondo`: ten 2xx helpers and forty 4xx/5xx helpers (`render_ok`,
+  `render_not_found`, `render_unprocessable`, …). 1xx and 3xx are omitted on
+  purpose — they have no meaning in a GraphQL response.
+- Field-level errors become one `errors[]` entry per message, tagged
+  `extensions.field`; `errors[0]` is always a summary carrying the message.
+- Configuration: `default_success_message`, `default_error_message`,
+  `include_request_id`, `camelize_keys`, `serializer`, `default_meta`,
+  `data_key`, `always_ok`, `auto_include`.
+- `always_ok` sends every response with HTTP 200 (Apollo-style clients).
+- `data_key` wraps Array / scalar payloads, since GraphQL `data` must be a map.
+- Railtie that includes the helpers into `ActionController::Base` / `::API`.
+  It skips auto-include when the `respondo` JSON gem is loaded (both define the
+  same helper names); include `RespondoGraphql::ControllerHelpers` in the
+  GraphQL controller instead, where it takes precedence over the parent's helpers.
+- `rails generate respondo_graphql:install` — interactive setup that writes
+  `config/initializers/respondo_graphql.rb`.

data/README.md

@@ -0,0 +1,143 @@
+<div align="center">
+
+# RespondoGraphql
+
+**Consistent GraphQL-spec responses for Rails controllers — in one line.**
+
+</div>
+
+---
+
+`respondo-graphql` is the GraphQL sibling of [`respondo`](https://github.com/spatelpatidar/respondo) (JSON). It is a **standalone gem**: it has no dependency on `respondo`, its own namespace (`RespondoGraphql`), its own config, and its own generator. Install either one, or both.
+
+It gives your controllers one expressive helper per situation (`render_ok`, `render_not_found`, `render_unprocessable`, …) and always answers in the GraphQL response shape: `data`, `errors`, `extensions`.
+
+## Install
+
+```ruby
+# Gemfile
+gem "respondo-graphql"
+```
+
+```bash
+bundle install
+rails generate respondo_graphql:install
+```
+
+The Railtie includes the helpers into `ActionController::Base` and `ActionController::API` for you. (If the `respondo` JSON gem is installed too, see [Using both gems](#using-both-gems).)
+
+## Usage
+
+```ruby
+class GraphqlController < ApplicationController
+  def show
+    user = User.find_by(id: params[:id])
+    return render_not_found(message: "User not found") unless user
+
+    render_ok(data: { user: user }, message: "User fetched")
+  end
+
+  def create
+    user = User.new(user_params)
+    if user.save
+      render_created(data: { user: user }, message: "Account created")
+    else
+      render_unprocessable(message: "Validation failed", errors: user.errors)
+    end
+  end
+end
+```
+
+**Success** — `render_ok(data: { user: { id: 1 } }, message: "User fetched")`
+
+```json
+{
+  "data": { "user": { "id": 1 } },
+  "extensions": { "message": "User fetched", "timestamp": "2026-10-04T10:30:00Z", "code": 200, "status": "ok" }
+}
+```
+
+**Failure** — `data` is `null`, and `errors[0]` is always a summary carrying your message. Field-level errors follow, one entry per message:
+
+```json
+{
+  "errors": [
+    { "message": "Validation failed",
+      "extensions": { "code": "UNPROCESSABLE_CONTENT", "http": { "status": 422 } } },
+    { "message": "email is invalid",
+      "extensions": { "code": "UNPROCESSABLE_CONTENT", "http": { "status": 422 }, "field": "email" } }
+  ],
+  "data": null,
+  "extensions": { "message": "Validation failed", "timestamp": "2026-10-04T10:30:00Z", "code": 422, "status": "unprocessable_content" }
+}
+```
+
+| What you pass | Where it ends up |
+|---|---|
+| `data:` | `data` — always a map or `null` |
+| `message:` | `extensions.message`, and `errors[0].message` on failure |
+| `meta:` / `pagination:` | `extensions` |
+| `errors: { field: [...] }` | one `errors[]` entry per message, tagged `extensions.field` |
+| success vs. failure | presence of the `errors` array |
+
+GraphQL requires `data` to be a map, so an Array or scalar payload is wrapped as `{ "result": [...] }` (rename it with `config.data_key`).
+
+## Helpers
+
+Same names and signatures as the `respondo` JSON gem.
+
+| Group | Helpers | Arguments |
+|---|---|---|
+| 2xx with payload | `render_ok` `render_created` `render_accepted` `render_non_authoritative` `render_partial_content` `render_multi_status` `render_already_reported` `render_im_used` | `data:` `message:` `meta:` `pagination:` |
+| 2xx no payload | `render_no_content` `render_reset_content` | `message:` `meta:` `pagination:` |
+| 4xx / 5xx | `render_bad_request` `render_unauthorized` `render_forbidden` `render_not_found` `render_conflict` `render_unprocessable` `render_too_many_requests` `render_server_error` `render_service_unavailable` … (40 in total) | `message:` `errors:` `meta:` |
+
+1xx (informational) and 3xx (redirect) helpers are deliberately left out: they are transport-level and have no meaning in a GraphQL response. The full list is in `RespondoGraphql::ControllerHelpers::SUCCESS_HELPERS` and `ERROR_HELPERS`.
+
+## Configuration
+
+```ruby
+# config/initializers/respondo_graphql.rb  (written by the generator)
+RespondoGraphql.configure do |config|
+  config.default_success_message = "Success"
+  config.default_error_message   = "An error occurred"
+  config.include_request_id      = false   # adds request_id to extensions
+  config.camelize_keys           = false   # created_at -> createdAt
+  config.always_ok               = false   # see below
+  config.data_key                = :result # wrapper for Array / scalar data
+  config.default_meta            = { api_version: "v1" }
+  config.serializer              = ->(obj) { MySerializer.new(obj).as_json }
+  config.auto_include            = true    # see "Using both gems"
+end
+```
+
+**`always_ok`** — many GraphQL clients, Apollo among them, treat non-2xx responses as network failures. Set `config.always_ok = true` to send every response with HTTP 200 and let the `errors` array carry the failure. The default (`false`) keeps each helper's own status (404 for `render_not_found`, …).
+
+## Using both gems
+
+`respondo` and `respondo-graphql` define the same helper names (`render_ok`, …), so they must not both be auto-included into every controller — whichever loaded last would silently win. When the Railtie sees that `respondo` is loaded, it **skips auto-include**. Keep `respondo` for your REST controllers and include the GraphQL helpers where you want them:
+
+```ruby
+class GraphqlController < ApplicationController
+  include RespondoGraphql::ControllerHelpers   # wins over respondo's helpers in this controller
+end
+```
+
+You can also turn auto-include off yourself with `config.auto_include = false`.
+
+## When to use this vs. graphql-ruby
+
+Your GraphQL schema already produces valid responses for queries and mutations. RespondoGraphql is for everything your controller answers *outside* the schema — authentication failures, rate limits, malformed requests, REST-style endpoints that speak GraphQL-shaped JSON — so those responses look the same as the rest.
+
+## Development
+
+```bash
+git clone https://github.com/spatelpatidar/respondo-graphql
+cd respondo-graphql
+bundle install
+bundle exec rspec
+```
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/generators/respondo_graphql/install/install_generator.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "fileutils"
+
+module RespondoGraphql
+  module Generators
+    # rails generate respondo_graphql:install
+    #
+    # Asks a few questions and writes config/initializers/respondo_graphql.rb.
+    # All output goes through $stdout (never Thor's `say`) so it is not echoed twice.
+    class InstallGenerator < Rails::Generators::Base
+      desc "Interactive setup — creates config/initializers/respondo_graphql.rb with your preferences."
+
+      def run_interactive_setup
+        out banner
+        out blank
+
+        unless confirm("  Ready to configure RespondoGraphql? (y/n) ")
+          out blank
+          out line(yellow("  Skipped. Run this again any time:"))
+          out line("    rails generate respondo_graphql:install")
+          out blank
+          return
+        end
+
+        @cfg = {}
+
+        step_api_version
+        step_request_id
+        step_camelize
+        step_always_ok
+
+        print_summary
+        write_initializer
+        print_done
+      end
+
+      private
+
+      # =========================================================================
+      # Steps
+      # =========================================================================
+
+      def step_api_version
+        out section("API version")
+        out line("  Added to the extensions block of every response (e.g. v1, v2).")
+        out blank
+        @cfg[:api_version] = prompt_default("v1")
+      end
+
+      def step_request_id
+        out section("Request ID")
+        out line("  Include Rails request.request_id in every response's extensions —")
+        out line("  useful for log correlation and debugging.")
+        out blank
+        @cfg[:include_request_id] = confirm("  Include request_id in every response? (y/n) ")
+      end
+
+      def step_camelize
+        out section("Key Format")
+        out line("  CamelCase all response keys:")
+        out line(yellow('    { "data": { "createdAt": "...", "userId": 1 } }'))
+        out blank
+        @cfg[:camelize_keys] = confirm("  Camelize all response keys? (y/n) ")
+      end
+
+      def step_always_ok
+        out section("HTTP status")
+        out line("  Many GraphQL clients (e.g. Apollo) treat non-2xx responses as network")
+        out line("  errors. Answer y to always send HTTP 200 and report failures in `errors`.")
+        out line("  Answer n to keep each helper's status (404 for render_not_found, ...).")
+        out blank
+        @cfg[:always_ok] = confirm("  Always send HTTP 200? (y/n) ")
+      end
+
+      # =========================================================================
+      # Summary
+      # =========================================================================
+
+      def print_summary
+        out blank
+        out divider
+        out line(cyan("  Configuration Summary"))
+        out divider
+        out blank
+        summary_row "API version",        api_version.empty? ? "(none)" : api_version
+        summary_row "Include request_id", @cfg[:include_request_id]
+        summary_row "Camelize keys",      @cfg[:camelize_keys]
+        summary_row "Always HTTP 200",    @cfg[:always_ok]
+        out blank
+        out divider
+        out blank
+      end
+
+      def summary_row(label, value)
+        shown = value == true ? green(value.inspect) : yellow(value.is_a?(String) ? value : value.inspect)
+        out "  #{"#{label}:".ljust(24)}#{shown}\n"
+      end
+
+      def api_version
+        @cfg[:api_version].to_s
+      end
+
+      # =========================================================================
+      # Write file
+      # =========================================================================
+
+      def write_initializer
+        dir  = File.join(destination_root, "config", "initializers")
+        path = File.join(dir, "respondo_graphql.rb")
+        FileUtils.mkdir_p(dir)
+        File.write(path, build_content)
+        out line(green("  ✅  Created config/initializers/respondo_graphql.rb"))
+        out blank
+      end
+
+      def build_content
+        lines = []
+        lines << "# frozen_string_literal: true"
+        lines << ""
+        lines << "# RespondoGraphql initializer"
+        lines << "# Generated by: rails generate respondo_graphql:install"
+        lines << "# RespondoGraphql version: #{RespondoGraphql::VERSION}"
+        lines << ""
+        lines << "RespondoGraphql.configure do |config|"
+        lines << "  # Fallback messages when a helper is called without message:"
+        lines << "  config.default_success_message = \"Success\""
+        lines << "  config.default_error_message   = \"An error occurred\""
+        lines << ""
+        lines << "  # Include Rails request.request_id in every response's extensions."
+        lines << "  config.include_request_id = #{@cfg[:include_request_id] ? true : false}"
+        lines << ""
+        lines << "  # CamelCase all response keys."
+        lines << "  config.camelize_keys = #{@cfg[:camelize_keys] ? true : false}"
+        lines << ""
+        lines << "  # Send every response with HTTP 200; failures are reported in `errors`."
+        lines << "  config.always_ok = #{@cfg[:always_ok] ? true : false}"
+        lines << ""
+        lines << "  # GraphQL `data` must be a map: Array / scalar payloads are wrapped under this key."
+        lines << "  config.data_key = :result"
+        lines << ""
+        lines << "  # Static fields merged into the extensions block of every response."
+        lines << (api_version.empty? ? "  config.default_meta = {}" : "  config.default_meta = { api_version: #{api_version.inspect} }")
+        lines << ""
+        lines << "  # Custom serializer — receives the payload, returns a Hash/Array."
+        lines << "  # config.serializer = ->(obj) { MySerializer.new(obj).as_json }"
+        lines << ""
+        lines << "  # Helpers are included into your controllers automatically. This is skipped"
+        lines << "  # when the respondo (JSON) gem is also installed — include"
+        lines << "  # RespondoGraphql::ControllerHelpers in your GraphQL controller instead."
+        lines << "  # config.auto_include = false"
+        lines << "end"
+        lines << ""
+        lines.join("\n")
+      end
+
+      # =========================================================================
+      # Done
+      # =========================================================================
+
+      def print_done
+        out divider
+        out blank
+        out line(cyan("  🎉  RespondoGraphql is ready!"))
+        out blank
+        out line("  Next steps:")
+        out line("    1. Review   config/initializers/respondo_graphql.rb")
+        out line("    2. Use      render_ok / render_not_found / render_unprocessable ... in your controllers")
+        out line("    3. Re-run   rails generate respondo_graphql:install  to regenerate")
+        out blank
+        out divider
+        out blank
+      end
+
+      # =========================================================================
+      # Output primitives — all output goes through $stdout, never through Thor
+      # =========================================================================
+
+      def out(str)
+        $stdout.print str
+        $stdout.flush
+      end
+
+      def line(str)
+        "#{str}\n"
+      end
+
+      def blank
+        "\n"
+      end
+
+      def divider
+        "  #{cyan("─" * 68)}\n"
+      end
+
+      def section(title)
+        dashes = "─" * [0, 54 - title.length].max
+        "\n  #{cyan("┌─ #{title} #{dashes}┐")}\n\n"
+      end
+
+      def banner
+        green("\n  RespondoGraphql — GraphQL-spec responses for Rails  (v#{RespondoGraphql::VERSION})\n")
+      end
+
+      def prompt_default(default)
+        $stdout.print "  #{cyan("›")} #{yellow("[#{default}]")}: "
+        $stdout.flush
+        result = $stdin.gets.to_s.strip
+        result.empty? ? default.to_s : result
+      end
+
+      def confirm(question)
+        $stdout.print question
+        $stdout.flush
+        $stdin.gets.to_s.strip.downcase.start_with?("y")
+      end
+
+      def cyan(text)   = "\e[36m#{text}\e[0m"
+      def green(text)  = "\e[32m#{text}\e[0m"
+      def yellow(text) = "\e[33m#{text}\e[0m"
+    end
+  end
+end

data/lib/respondo-graphql.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Lets `gem "respondo-graphql"` be auto-required by Bundler.require
+# (Bundler requires the gem's own name, hyphen included).
+require_relative "respondo_graphql"

data/lib/respondo_graphql/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RespondoGraphql
+  # Global configuration for RespondoGraphql.
+  #
+  # @example
+  #   RespondoGraphql.configure do |config|
+  #     config.default_success_message = "OK"
+  #     config.include_request_id      = true
+  #     config.camelize_keys           = true
+  #     config.always_ok               = true
+  #   end
+  class Configuration
+    # Message used when none is supplied to a success helper
+    attr_accessor :default_success_message
+
+    # Message used when none is supplied to an error helper
+    attr_accessor :default_error_message
+
+    # When true, includes request.request_id in every extensions block (Rails only)
+    attr_accessor :include_request_id
+
+    # When true, all response keys are camelized (e.g. created_at -> createdAt)
+    attr_accessor :camelize_keys
+
+    # Custom serializer callable — receives (object) and returns a Hash/Array.
+    # Defaults to nil (built-in serialization strategy is used).
+    # @example config.serializer = ->(obj) { MySerializer.new(obj).as_json }
+    attr_accessor :serializer
+
+    # Static key-value pairs merged into every response's `extensions` block.
+    # @example config.default_meta = { api_version: "v1" }
+    attr_accessor :default_meta
+
+    # GraphQL requires `data` to be a map, so a payload that is an Array or a
+    # scalar is wrapped as { <data_key> => payload }. Hash payloads pass through.
+    attr_accessor :data_key
+
+    # When true every response is sent with HTTP 200, whatever the helper's
+    # status, and failures are reported through the `errors` array. Many GraphQL
+    # clients (e.g. Apollo) treat non-2xx responses as network failures.
+    # Defaults to false so helper status codes keep meaning what they say.
+    attr_accessor :always_ok
+
+    # When true (default) the Railtie includes the helpers into
+    # ActionController::Base / ::API, so no `include` is needed. It is skipped
+    # automatically when the respondo (JSON) gem is also loaded, because both
+    # gems define the same helper names — include RespondoGraphql::ControllerHelpers
+    # in your GraphQL controller instead.
+    attr_accessor :auto_include
+
+    def initialize
+      @default_success_message = "Success"
+      @default_error_message   = "An error occurred"
+      @include_request_id      = false
+      @camelize_keys           = false
+      @serializer              = nil
+      @default_meta            = {}
+      @data_key                = :result
+      @always_ok               = false
+      @auto_include            = true
+    end
+  end
+end

data/lib/respondo_graphql/controller_helpers.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module RespondoGraphql
+  # Mixed into Rails controllers to render GraphQL-spec responses with
+  # expressive, status-aware helpers.
+  #
+  # Success helpers (2xx) — accept data:, message:, meta:, pagination:
+  #   render_ok, render_created, render_accepted, render_non_authoritative,
+  #   render_partial_content, render_multi_status, render_already_reported,
+  #   render_im_used
+  #
+  # Success helpers (2xx) without a payload — accept message:, meta:, pagination:
+  #   render_no_content, render_reset_content
+  #
+  # Error helpers (4xx / 5xx) — accept message:, errors:, meta:
+  #   render_bad_request, render_unauthorized, render_payment_required,
+  #   render_forbidden, render_not_found, render_method_not_allowed,
+  #   render_not_acceptable, render_proxy_auth_required, render_request_timeout,
+  #   render_conflict, render_gone, render_length_required,
+  #   render_precondition_failed, render_payload_too_large, render_uri_too_long,
+  #   render_unsupported_media_type, render_range_not_satisfiable,
+  #   render_expectation_failed, render_im_a_teapot, render_misdirected_request,
+  #   render_unprocessable, render_locked, render_failed_dependency,
+  #   render_too_early, render_upgrade_required, render_precondition_required,
+  #   render_too_many_requests, render_request_header_fields_too_large,
+  #   render_unavailable_for_legal_reasons, render_server_error,
+  #   render_not_implemented, render_bad_gateway, render_service_unavailable,
+  #   render_gateway_timeout, render_http_version_not_supported,
+  #   render_variant_also_negotiates, render_insufficient_storage,
+  #   render_loop_detected, render_not_extended,
+  #   render_network_authentication_required
+  #
+  # 1xx (informational) and 3xx (redirect) helpers are intentionally not
+  # provided: they are transport-level and have no meaning in a GraphQL response.
+  module ControllerHelpers
+    # name => [numeric code, Rails status symbol, default message, takes data?]
+    SUCCESS_HELPERS = {
+      ok:                { code: 200, status: :ok,                            message: nil,                                       data: true  },
+      created:           { code: 201, status: :created,                       message: "Created successfully",                    data: true  },
+      accepted:          { code: 202, status: :accepted,                      message: "Request accepted and is being processed", data: true  },
+      non_authoritative: { code: 203, status: :non_authoritative_information, message: "Non-authoritative information",           data: true  },
+      no_content:        { code: 204, status: :no_content,                    message: "Deleted successfully",                    data: false },
+      reset_content:     { code: 205, status: :reset_content,                 message: "Reset content",                           data: false },
+      partial_content:   { code: 206, status: :partial_content,               message: "Partial content returned",                data: true  },
+      multi_status:      { code: 207, status: :multi_status,                  message: "Multi-status response",                   data: true  },
+      already_reported:  { code: 208, status: :already_reported,              message: "Already reported",                        data: true  },
+      im_used:           { code: 226, status: :im_used,                       message: "IM used",                                 data: true  }
+    }.freeze
+
+    # name => [numeric code, Rails status symbol, default message]
+    ERROR_HELPERS = {
+      bad_request:                     { code: 400, status: :bad_request,                     message: "Bad request" },
+      unauthorized:                    { code: 401, status: :unauthorized,                    message: "Unauthorized" },
+      payment_required:                { code: 402, status: :payment_required,                message: "Payment required to access this resource" },
+      forbidden:                       { code: 403, status: :forbidden,                       message: "You do not have permission to perform this action" },
+      not_found:                       { code: 404, status: :not_found,                       message: "Resource not found" },
+      method_not_allowed:              { code: 405, status: :method_not_allowed,              message: "HTTP method not allowed" },
+      not_acceptable:                  { code: 406, status: :not_acceptable,                  message: "Requested format not acceptable" },
+      proxy_auth_required:             { code: 407, status: :proxy_authentication_required,   message: "Proxy authentication required" },
+      request_timeout:                 { code: 408, status: :request_timeout,                 message: "Request timed out" },
+      conflict:                        { code: 409, status: :conflict,                        message: "Resource conflict" },
+      gone:                            { code: 410, status: :gone,                            message: "Resource no longer available" },
+      length_required:                 { code: 411, status: :length_required,                 message: "Content-Length header required" },
+      precondition_failed:             { code: 412, status: :precondition_failed,             message: "Precondition failed" },
+      payload_too_large:               { code: 413, status: :payload_too_large,               message: "Payload too large" },
+      uri_too_long:                    { code: 414, status: :uri_too_long,                    message: "URI too long" },
+      unsupported_media_type:          { code: 415, status: :unsupported_media_type,          message: "Unsupported media type" },
+      range_not_satisfiable:           { code: 416, status: :range_not_satisfiable,           message: "Range not satisfiable" },
+      expectation_failed:              { code: 417, status: :expectation_failed,              message: "Expectation failed" },
+      im_a_teapot:                     { code: 418, status: :im_a_teapot,                     message: "I'm a teapot" },
+      misdirected_request:             { code: 421, status: :misdirected_request,             message: "Misdirected request" },
+      unprocessable:                   { code: 422, status: :unprocessable_content,           message: "Validation failed" },
+      locked:                          { code: 423, status: :locked,                          message: "Resource is locked" },
+      failed_dependency:               { code: 424, status: :failed_dependency,               message: "Failed dependency" },
+      too_early:                       { code: 425, status: :too_early,                       message: "Too early" },
+      upgrade_required:                { code: 426, status: :upgrade_required,                message: "Upgrade required" },
+      precondition_required:           { code: 428, status: :precondition_required,           message: "Precondition required" },
+      too_many_requests:               { code: 429, status: :too_many_requests,               message: "Too many requests. Please slow down." },
+      request_header_fields_too_large: { code: 431, status: :request_header_fields_too_large, message: "Request header fields too large" },
+      unavailable_for_legal_reasons:   { code: 451, status: :unavailable_for_legal_reasons,   message: "Unavailable for legal reasons" },
+      server_error:                    { code: 500, status: :internal_server_error,           message: "An unexpected error occurred" },
+      not_implemented:                 { code: 501, status: :not_implemented,                 message: "This feature is not yet implemented" },
+      bad_gateway:                     { code: 502, status: :bad_gateway,                     message: "Bad gateway — upstream service error" },
+      service_unavailable:             { code: 503, status: :service_unavailable,             message: "Service temporarily unavailable" },
+      gateway_timeout:                 { code: 504, status: :gateway_timeout,                 message: "Gateway timeout — upstream service did not respond" },
+      http_version_not_supported:      { code: 505, status: :http_version_not_supported,      message: "HTTP version not supported" },
+      variant_also_negotiates:         { code: 506, status: :variant_also_negotiates,         message: "Variant also negotiates" },
+      insufficient_storage:            { code: 507, status: :insufficient_storage,            message: "Insufficient storage" },
+      loop_detected:                   { code: 508, status: :loop_detected,                   message: "Loop detected" },
+      not_extended:                    { code: 510, status: :not_extended,                    message: "Not extended" },
+      network_authentication_required: { code: 511, status: :network_authentication_required, message: "Network authentication required" }
+    }.freeze
+
+    SUCCESS_HELPERS.each do |name, spec|
+      default_message = spec[:message]
+
+      if spec[:data]
+        # e.g. render_ok(data: @user, message: "User fetched", meta: {}, pagination: nil)
+        define_method(:"render_#{name}") do |data: nil, message: default_message, meta: {}, pagination: nil|
+          render_success(data: data, message: message, meta: meta, pagination: pagination,
+                         code: spec[:code], status: spec[:status])
+        end
+      else
+        # e.g. render_no_content(message: "Deleted", meta: {}, pagination: nil)
+        define_method(:"render_#{name}") do |message: default_message, meta: {}, pagination: nil|
+          render_success(data: nil, message: message, meta: meta, pagination: pagination,
+                         code: spec[:code], status: spec[:status])
+        end
+      end
+    end
+
+    ERROR_HELPERS.each do |name, spec|
+      default_message = spec[:message]
+
+      # e.g. render_not_found(message: "User not found", errors: nil, meta: {})
+      define_method(:"render_#{name}") do |message: default_message, errors: nil, meta: {}|
+        render_error(message: message, errors: errors, meta: meta, code: spec[:code], status: spec[:status])
+      end
+    end
+
+    private
+
+    # =========================================================================
+    # Core DSL — every helper delegates to these two
+    # =========================================================================
+
+    # Render a successful GraphQL response.
+    #
+    # @param data       [Object]          payload — AR model, collection, Hash, Array, nil
+    # @param message    [String]          human-readable description (goes in extensions)
+    # @param meta       [Hash]            extra fields merged into extensions
+    # @param pagination [Hash, nil]       pagination hash built by the caller
+    # @param code       [Integer, nil]    numeric HTTP code recorded in extensions
+    # @param status     [Symbol, Integer] HTTP status (default: :ok / 200)
+    def render_success(data: nil, message: nil, meta: {}, code: nil, pagination: nil, status: :ok)
+      merged_meta = code ? meta.merge(code: code, status: status) : meta
+
+      payload = ResponseBuilder.new(
+        success:    true,
+        data:       data,
+        message:    message,
+        meta:       merged_meta,
+        pagination: pagination,
+        request:    try(:request)
+      ).build
+
+      render json: payload, status: respondo_graphql_status(status)
+    end
+
+    # Render a failed GraphQL response: data is null, `errors` explains why.
+    #
+    # @param message [String]                      human-readable error description
+    # @param errors  [Hash, ActiveModel::Errors]   field-level errors
+    # @param code    [Integer, String, nil]        HTTP code (Integer) or machine-readable code (String)
+    # @param meta    [Hash]                        extra fields merged into extensions
+    # @param status  [Symbol, Integer]             HTTP status (default: :unprocessable_content / 422)
+    def render_error(message: nil, errors: nil, code: nil, meta: {}, status: :unprocessable_content)
+      merged_meta = code ? meta.merge(code: code, status: status) : meta
+
+      payload = ResponseBuilder.new(
+        success: false,
+        data:    nil,
+        message: message,
+        meta:    merged_meta,
+        errors:  extract_errors(errors),
+        request: try(:request)
+      ).build
+
+      render json: payload, status: respondo_graphql_status(status)
+    end
+
+    # With config.always_ok every response is sent as HTTP 200.
+    def respondo_graphql_status(status)
+      RespondoGraphql.config.always_ok ? :ok : status
+    end
+
+    # Normalize errors into a plain Hash regardless of source type.
+    def extract_errors(errors)
+      return nil if errors.nil?
+      return errors.to_hash if defined?(ActiveModel::Errors) && errors.is_a?(ActiveModel::Errors)
+      return errors if errors.is_a?(Hash)
+      return { base: errors } if errors.is_a?(Array)
+      return { base: [errors] } if errors.is_a?(String)
+
+      nil
+    end
+  end
+end

data/lib/respondo_graphql/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RespondoGraphql
+  # Includes RespondoGraphql::ControllerHelpers into ActionController::Base and
+  # ActionController::API so no `include` is needed in ApplicationController.
+  #
+  # Skipped when config.auto_include is false, or when the respondo (JSON) gem
+  # is also loaded — both gems define the same helper names, so the last one
+  # included would silently win in every controller. In that case include
+  # RespondoGraphql::ControllerHelpers in your GraphQL controller yourself; a
+  # module included in a subclass takes precedence over its parent's helpers.
+  class Railtie < Rails::Railtie
+    initializer "respondo_graphql.include_controller_helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include RespondoGraphql::ControllerHelpers if RespondoGraphql.auto_include?
+      end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        include RespondoGraphql::ControllerHelpers if RespondoGraphql.auto_include?
+      end
+    end
+  end
+end

data/lib/respondo_graphql/response_builder.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RespondoGraphql
+  # Builds a GraphQL-spec response envelope.
+  #
+  #   {
+  #     errors:     [ { message:, extensions: { code:, http: { status: } } } ],  # only on failure
+  #     data:       Hash | nil,
+  #     extensions: { message:, timestamp:, ...meta }
+  #   }
+  #
+  # On failure `data` is null and `errors` always starts with a summary entry
+  # carrying the helper's message, followed by one entry per field-level error,
+  # so `errors[0].message` is always safe to show to a user.
+  #
+  # The extensions block always contains the message and an ISO8601 timestamp,
+  # plus request_id (config.include_request_id), config.default_meta,
+  # caller-supplied meta, pagination, and the helper's code/status.
+  class ResponseBuilder
+    # @param success    [Boolean]
+    # @param data       [Object]   anything — serialized automatically
+    # @param message    [String]
+    # @param meta       [Hash]     caller-supplied extra extensions (merged in)
+    # @param errors     [Hash]     field-level errors, e.g. { email: ["is invalid"] }
+    # @param pagination [Hash, nil] plain pagination hash supplied by the caller
+    # @param request    [Object]   ActionDispatch::Request (for request_id)
+    def initialize(success:, data: nil, message: nil, meta: {}, errors: nil,
+                   pagination: nil, request: nil)
+      @success    = success
+      @raw_data   = data
+      @message    = message
+      @extra_meta = meta || {}
+      @errors     = errors
+      @pagination = pagination
+      @request    = request
+    end
+
+    # @return [Hash] the complete GraphQL response payload
+    def build
+      payload = {}
+
+      errors = build_errors
+      payload[:errors] = errors unless errors.empty?
+
+      payload[:data]       = build_data
+      payload[:extensions] = { message: resolve_message }.merge(build_meta)
+
+      apply_camelize(payload)
+    end
+
+    private
+
+    def resolve_message
+      return @message if @message && !@message.empty?
+
+      @success ? RespondoGraphql.config.default_success_message : RespondoGraphql.config.default_error_message
+    end
+
+    # GraphQL requires `data` to be a map (or null when execution failed).
+    def build_data
+      return nil unless @success
+
+      data = Serializer.call(@raw_data)
+      return data if data.nil? || data.is_a?(Hash)
+
+      { RespondoGraphql.config.data_key.to_sym => data }
+    end
+
+    def build_errors
+      return [] if @success
+
+      [{ message: resolve_message, extensions: error_extensions }] + field_error_entries
+    end
+
+    # One entry per field message, e.g. { email: ["is invalid"] } becomes
+    #   { message: "email is invalid", extensions: { code: ..., field: "email" } }
+    def field_error_entries
+      return [] unless @errors.is_a?(Hash)
+
+      @errors.flat_map do |field, messages|
+        Array(messages).map do |text|
+          label = field.to_s == "base" ? text.to_s : "#{field} #{text}"
+          { message: label, extensions: error_extensions.merge(field: field.to_s) }
+        end
+      end
+    end
+
+    def error_extensions
+      extensions = { code: error_code }
+      extensions[:http] = { status: http_status } if http_status
+      extensions
+    end
+
+    # A String `code:` passed to render_error is already machine-readable and
+    # is used as-is; otherwise the status symbol is used, e.g. :not_found
+    # becomes "NOT_FOUND". Falls back to "ERROR" when neither is available.
+    def error_code
+      custom = @extra_meta[:code]
+      return custom if custom.is_a?(String) && !custom.empty?
+
+      status = @extra_meta[:status]
+      status.is_a?(Symbol) || status.is_a?(String) ? status.to_s.upcase : "ERROR"
+    end
+
+    # The numeric HTTP status the helper stands for, when known.
+    def http_status
+      [@extra_meta[:code], @extra_meta[:status]].find { |value| value.is_a?(Integer) }
+    end
+
+    def build_meta
+      config = RespondoGraphql.config
+      meta   = {}
+
+      # 1. Request ID first (opt-in)
+      meta[:request_id] = @request.request_id if config.include_request_id && @request.respond_to?(:request_id)
+
+      # 2. Timestamp second
+      meta[:timestamp] = current_timestamp
+
+      # 3. Global defaults (lowest priority), then caller-supplied meta
+      meta.merge!(config.default_meta)
+      meta.merge!(@extra_meta)
+
+      # 4. Pagination — plain hash from the caller
+      meta[:pagination] = @pagination if @pagination.is_a?(Hash) && !@pagination.empty?
+
+      # 5. Re-pin code and status to the very end
+      code   = meta.delete(:code)
+      status = meta.delete(:status)
+      meta[:code]   = code   if code
+      meta[:status] = status if status
+
+      meta
+    end
+
+    def current_timestamp
+      if Time.respond_to?(:current)
+        Time.current.iso8601
+      else
+        Time.now.utc.iso8601
+      end
+    end
+
+    def apply_camelize(hash)
+      return hash unless RespondoGraphql.config.camelize_keys
+
+      camelize_hash(hash)
+    end
+
+    def camelize_hash(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(key, value), memo| memo[camelize_key(key)] = camelize_hash(value) }
+      when Array
+        obj.map { |item| camelize_hash(item) }
+      else
+        obj
+      end
+    end
+
+    def camelize_key(key)
+      key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }.to_sym
+    end
+  end
+end

data/lib/respondo_graphql/serializer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RespondoGraphql
+  # Responsible for converting any Ruby object into a JSON-safe Hash or Array.
+  #
+  # Priority order:
+  #   1. Custom serializer from RespondoGraphql.config (if set)
+  #   2. ActiveRecord::Base / ActiveRecord::Relation
+  #   3. ActiveModel::Errors / objects responding to #errors
+  #   4. Objects responding to #as_json or #to_h
+  #   5. Arrays — each element is serialized recursively
+  #   6. Primitives — returned as-is
+  module Serializer
+    module_function
+
+    # @param object [Object] anything — AR model, collection, error, hash, array, primitive
+    # @return [Hash, Array, String, Numeric, nil]
+    def call(object)
+      return nil if object.nil?
+
+      # 1. Custom serializer wins
+      if RespondoGraphql.config.serializer
+        return RespondoGraphql.config.serializer.call(object)
+      end
+
+      # 2. ActiveRecord::Relation or any object with #map (lazy collections)
+      if ar_relation?(object)
+        return object.map { |record| serialize_record(record) }
+      end
+
+      # 3. Array — recurse
+      if object.is_a?(Array)
+        return object.map { |item| call(item) }
+      end
+
+      # 4. ActiveRecord model instance
+      if ar_model?(object)
+        return serialize_record(object)
+      end
+
+      # 5. ActiveModel::Errors object
+      if active_model_errors?(object)
+        return serialize_errors(object)
+      end
+
+      # 6. Exception / StandardError
+      if object.is_a?(Exception)
+        return { message: object.message }
+      end
+
+      # 7. Hash — recursively serialize values
+      if object.is_a?(Hash)
+        return object.transform_values { |v| call(v) }
+      end
+
+      # 8. Responds to #as_json (ActiveSupport)
+      if object.respond_to?(:as_json)
+        return object.as_json
+      end
+
+      # 9. Responds to #to_h
+      if object.respond_to?(:to_h)
+        return object.to_h
+      end
+
+      # 10. Primitive — return as-is
+      object
+    end
+
+    private
+
+    module_function
+
+    def ar_relation?(object)
+      defined?(ActiveRecord::Relation) &&
+        object.is_a?(ActiveRecord::Relation)
+    end
+
+    def ar_model?(object)
+      defined?(ActiveRecord::Base) &&
+        object.is_a?(ActiveRecord::Base)
+    end
+
+    def active_model_errors?(object)
+      defined?(ActiveModel::Errors) &&
+        object.is_a?(ActiveModel::Errors)
+    end
+
+    def serialize_record(record)
+      if record.respond_to?(:as_json)
+        record.as_json
+      elsif record.respond_to?(:to_h)
+        record.to_h
+      else
+        record
+      end
+    end
+
+    def serialize_errors(errors)
+      # ActiveModel::Errors — return { field: ["msg", ...] }
+      if errors.respond_to?(:to_hash)
+        errors.to_hash
+      elsif errors.respond_to?(:messages)
+        errors.messages
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/respondo_graphql/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RespondoGraphql
+  VERSION = "0.1.0"
+end

data/lib/respondo_graphql.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "respondo_graphql/version"
+require_relative "respondo_graphql/configuration"
+require_relative "respondo_graphql/serializer"
+require_relative "respondo_graphql/response_builder"
+require_relative "respondo_graphql/controller_helpers"
+
+# RespondoGraphql — consistent GraphQL-spec responses for Rails controllers.
+#
+# @example Configure once in an initializer
+#   # config/initializers/respondo_graphql.rb
+#   RespondoGraphql.configure do |config|
+#     config.camelize_keys = true
+#     config.always_ok     = true   # HTTP 200 for every response
+#   end
+#
+# @example Use in a controller
+#   class GraphqlController < ApplicationController
+#     def show
+#       render_ok(data: { user: User.find(params[:id]) }, message: "User fetched")
+#     end
+#   end
+#
+# @example Include manually (outside Rails, or next to the respondo JSON gem)
+#   class GraphqlController < ApplicationController
+#     include RespondoGraphql::ControllerHelpers
+#   end
+module RespondoGraphql
+  class << self
+    # @return [RespondoGraphql::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yield [RespondoGraphql::Configuration]
+    def configure
+      yield config
+    end
+
+    # Reset config (useful in tests)
+    def reset!
+      @config = Configuration.new
+    end
+
+    # Whether the Railtie should include the helpers into the base controllers.
+    # False when the user turned it off, or when the respondo (JSON) gem is
+    # loaded too (both define the same helper names).
+    def auto_include?
+      config.auto_include && !defined?(::Respondo::ControllerHelpers) ? true : false
+    end
+  end
+end
+
+# Auto-integrate with Rails if present
+require_relative "respondo_graphql/railtie" if defined?(Rails::Railtie)

data/respondo-graphql.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/respondo_graphql/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "respondo-graphql"
+  spec.version       = RespondoGraphql::VERSION
+  spec.authors       = ["shailendra Kumar"]
+  spec.email         = ["shailendrapatidar00@gmail.com"]
+
+  spec.summary       = "Consistent GraphQL-spec responses for Rails controllers — data, errors, extensions."
+  spec.description   = <<~DESC
+    RespondoGraphql standardizes the GraphQL-style responses your Rails
+    controllers send: data, errors and extensions, built from one set of
+    expressive helpers (render_ok, render_not_found, render_unprocessable, ...).
+    Field errors become spec-compliant errors[] entries, message and meta live in
+    extensions, and HTTP statuses can optionally be pinned to 200.
+    Standalone gem — it does not depend on the respondo (JSON) gem.
+  DESC
+  spec.homepage      = "https://github.com/spatelpatidar/respondo-graphql"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata = {
+    "homepage_uri"          => spec.homepage,
+    "source_code_uri"       => spec.homepage,
+    "changelog_uri"         => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri"       => "#{spec.homepage}/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE.txt", "CHANGELOG.md", "respondo-graphql.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "railties",      "~> 8.1.3"
+  spec.add_development_dependency "rspec",         "~> 3.12"
+  spec.add_development_dependency "rake",          "~> 13.0"
+  spec.add_development_dependency "activesupport", "~> 8.1.3"
+  spec.add_development_dependency "simplecov",     "~> 0.22"
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: respondo-graphql
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- shailendra Kumar
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: |
+  RespondoGraphql standardizes the GraphQL-style responses your Rails
+  controllers send: data, errors and extensions, built from one set of
+  expressive helpers (render_ok, render_not_found, render_unprocessable, ...).
+  Field errors become spec-compliant errors[] entries, message and meta live in
+  extensions, and HTTP statuses can optionally be pinned to 200.
+  Standalone gem — it does not depend on the respondo (JSON) gem.
+email:
+- shailendrapatidar00@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/generators/respondo_graphql/install/install_generator.rb
+- lib/respondo-graphql.rb
+- lib/respondo_graphql.rb
+- lib/respondo_graphql/configuration.rb
+- lib/respondo_graphql/controller_helpers.rb
+- lib/respondo_graphql/railtie.rb
+- lib/respondo_graphql/response_builder.rb
+- lib/respondo_graphql/serializer.rb
+- lib/respondo_graphql/version.rb
+- respondo-graphql.gemspec
+homepage: https://github.com/spatelpatidar/respondo-graphql
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/spatelpatidar/respondo-graphql
+  source_code_uri: https://github.com/spatelpatidar/respondo-graphql
+  changelog_uri: https://github.com/spatelpatidar/respondo-graphql/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/spatelpatidar/respondo-graphql/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Consistent GraphQL-spec responses for Rails controllers — data, errors, extensions.
+test_files: []