respondo 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f627c02a80d4eb8ab106714e2739d38b17545a93d1772e052497850c8a56f437
-  data.tar.gz: 8f078c4540d8182fc59ccdc8c539b29835ccb9f7cf5d781b2ae389e0a9c04461
+  metadata.gz: fb5118a5648863ec54d68805d897485f40da5b81b9b628b9b9a08d6ee2f735d7
+  data.tar.gz: 4282b491b0bd587ba668e7accaf19f6dfb879cc61261d64d744de69c803ae8a0
 SHA512:
-  metadata.gz: 4677d2d32eaa9441032829a6414cd81d24d831b61ce45e0fd3586c4d804745d9307a1bc375b280b0801d53812b6accb656ae28ac1c36dc858befa51c3098b2aa
-  data.tar.gz: 937d964de71ac65cd5d13df236cf74012b390cee914c13b8078a653db7d7a2273037593fad1981df41a59280e3cba677f5ede00ea6992b07058b90a5456645f6
+  metadata.gz: 4ae4daae47ef9c2c66388fc6d8f3a915b66439208fafa25b7046234813229704de0e53863921f2b4e2100817218b2a315ef40a564c5f672a9848194e55814906
+  data.tar.gz: 86a9ecb6864c1bba75dc4d47941bd0f80c837f4dbc72ed424526e1dad3f05ead92b738a417a239f3fb160e7043fc465418fe6670948be147399ea90ee3ce85d8

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## [2.1.0] — Interactive Install Generator
+
+### Added
+
+#### `rails generate respondo:install` — interactive setup wizard
+A new generator that walks developers through configuration interactively at
+install time, writing a fully commented `config/initializers/respondo.rb` so
+they never have to read the README to get started.
+
+**Usage:**
+```bash
+rails generate respondo:install
+```
+
+**What the wizard collects:**
+
+| Prompt | Config written |
+|--------|---------------|
+| Project / app name | Comment header in initializer |
+| API version | Auto-added to `config.default_meta` |
+| Default success message | `config.default_success_message` |
+| Default error message | `config.default_error_message` |
+| Include request ID? | `config.include_request_id` |
+| Camelize keys? | `config.camelize_keys` |
+| Extra global meta fields | `config.default_meta` (merged with api_version) |
+| Custom serializer stub? | Commented example added to initializer |
+
+**Example output — `config/initializers/respondo.rb`:**
+```ruby
+# frozen_string_literal: true
+
+# Respondo initializer — MyApp
+# Generated by: rails generate respondo:install
+# Respondo version: 2.1.0
+
+Respondo.configure do |config|
+
+  # ── Messages ─────────────────────────────────────────────────────────
+  config.default_success_message = "Success"
+  config.default_error_message   = "Something went wrong"
+
+  # ── Request ID ───────────────────────────────────────────────────────
+  config.include_request_id = true
+
+  # ── Key Format ───────────────────────────────────────────────────────
+  config.camelize_keys = true
+
+  # ── Global Meta ──────────────────────────────────────────────────────
+  config.default_meta = {
+    api_version: "v1",
+    platform: "mobile"
+  }
+
+  # ── Custom Serializer ────────────────────────────────────────────────
+  # config.serializer = ->(obj) { MySerializer.new(obj).as_json }
+
+end
+```
+
+**Generator file location:**
+```
+lib/generators/respondo/install/install_generator.rb
+```
+
+Rails auto-discovers this path — no manual require needed. Re-running the
+generator overwrites the existing initializer with fresh answers.
+
+---
+
 ## [2.0.0] — Full HTTP Coverage
 
 ### Breaking Changes

data/README.md

@@ -42,6 +42,78 @@ gem "respondo"
 
 ## Setup
 
+### ✅ Recommended — use the install generator
+
+After adding the gem, run:
+
+```bash
+rails generate respondo:install
+```
+
+The interactive wizard walks you through every option and writes a fully commented `config/initializers/respondo.rb` tailored to your project. No need to read the full README or copy-paste config by hand.
+
+```
+  ┌─ Project Info ─────────────────────────────────────────────────────┐
+
+  Project / app name
+  (Used as a comment header in the initializer)
+  › [MyApp]:
+
+  API version  (e.g. v1 — added to every response meta block)
+  › [v1]:
+
+  ┌─ Response Messages ────────────────────────────────────────────────┐
+
+  Default success message
+  › [Success]:
+
+  Default error message
+  › [An error occurred]:
+
+  ...
+```
+
+The generator produces a file like this:
+
+```ruby
+# frozen_string_literal: true
+
+# Respondo initializer — MyApp
+# Generated by: rails generate respondo:install
+# Respondo version: 2.1.0
+
+Respondo.configure do |config|
+
+  # ── Messages ─────────────────────────────────────────────────────────
+  config.default_success_message = "Success"
+  config.default_error_message   = "Something went wrong"
+
+  # ── Request ID ───────────────────────────────────────────────────────
+  config.include_request_id = true
+
+  # ── Key Format ───────────────────────────────────────────────────────
+  config.camelize_keys = true
+
+  # ── Global Meta ──────────────────────────────────────────────────────
+  config.default_meta = {
+    api_version: "v1",
+    platform: "mobile"
+  }
+
+  # ── Custom Serializer ────────────────────────────────────────────────
+  # config.serializer = ->(obj) { MySerializer.new(obj).as_json }
+
+end
+```
+
+Re-run the generator any time to regenerate with different answers — it overwrites the existing initializer.
+
+---
+
+### Manual setup (alternative)
+
+If you prefer to write the initializer yourself, create `config/initializers/respondo.rb`:
+
 ```ruby
 # config/initializers/respondo.rb
 Respondo.configure do |config|
@@ -770,13 +842,17 @@ class ApiResponse<T> {
 ```
 lib/
 ├── respondo.rb                    # Entry point, configure, Railtie hook
-└── respondo/
-    ├── version.rb                 # VERSION
-    ├── configuration.rb           # Config with defaults
-    ├── serializer.rb              # Auto-detects and serializes any object
-    ├── response_builder.rb        # Assembles the final Hash
-    ├── controller_helpers.rb      # All render_* helpers (1xx–5xx)
-    └── railtie.rb                 # Auto-includes into Rails controllers
+├── respondo/
+│   ├── version.rb                 # VERSION
+│   ├── configuration.rb           # Config with defaults
+│   ├── serializer.rb              # Auto-detects and serializes any object
+│   ├── response_builder.rb        # Assembles the final Hash
+│   ├── controller_helpers.rb      # All render_* helpers (1xx–5xx)
+│   └── railtie.rb                 # Auto-includes into Rails controllers
+└── generators/
+    └── respondo/
+        └── install/
+            └── install_generator.rb   # rails generate respondo:install
 ```
 
 ---

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

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Respondo
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Interactive setup — creates config/initializers/respondo.rb with your preferences."
+
+      # We bypass Thor's `say` entirely for all display output and use
+      # $stdout.puts / print directly. This prevents Thor from re-echoing
+      # buffered output and causing duplicate lines in the terminal.
+
+      def run_interactive_setup
+        # out LOGO
+        out logo_with_version
+        out divider
+        out line("  This wizard will generate config/initializers/respondo.rb")
+        out line("  tailored to your project — no need to read the full README.")
+        out blank
+        out line(yellow("  All settings can be changed later by editing the initializer."))
+        out divider
+        out blank
+
+        unless confirm("  Ready to configure Respondo? (y/n) ")
+          out blank
+          out line(yellow("  Skipped. Run this again any time:"))
+          out line("    rails generate respondo:install")
+          out blank
+          return
+        end
+
+        @cfg = {}
+
+        step_project_info
+        step_messages
+        step_request_id
+        step_camelize
+        step_default_meta
+        step_serializer
+
+        print_summary
+        write_initializer
+        print_done
+      end
+
+      private
+
+      # =========================================================================
+      # Steps
+      # =========================================================================
+
+      def step_project_info
+        out section("Project Info")
+        out line("  Project / app name")
+        out line(yellow("  (Used as a comment header in the initializer)"))
+        @cfg[:project_name] = prompt_default(Rails.application.class.module_parent_name)
+
+        out blank
+        out line("  API version")
+        out line(yellow("  (e.g. v1 — added to every response meta block)"))
+        @cfg[:api_version] = prompt_default("v1")
+      end
+
+      def step_messages
+        out section("Response Messages")
+        out line("  Fallback messages used when you don't pass message: explicitly.")
+        out blank
+
+        out line("  Default success message")
+        @cfg[:default_success_message] = prompt_default("Success")
+
+        out blank
+        out line("  Default error message")
+        @cfg[:default_error_message] = prompt_default("An error occurred")
+      end
+
+      def step_request_id
+        out section("Request ID")
+        out line("  When enabled, Rails request.request_id is included in every")
+        out line("  response meta block — 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("  When enabled, all JSON keys are camelCased:")
+        out line(yellow('    { "createdAt": "...", "userId": 1 }'))
+        out line("  Recommended for Flutter, React, and JavaScript clients.")
+        out blank
+        @cfg[:camelize_keys] = confirm("  Camelize all response keys? (y/n) ")
+      end
+
+      def step_default_meta
+        out section("Global Meta Fields")
+        out line("  Static key=value pairs merged into the meta block of EVERY response.")
+        out line("  Example:  platform=mobile   environment=production")
+        out blank
+        out line(yellow("  Note: api_version from above is already included automatically."))
+        out blank
+
+        @cfg[:default_meta] = {}
+        return unless confirm("  Add extra global meta fields? (y/n) ")
+
+        out blank
+        out line("  Enter key=value one at a time. Blank line to finish.")
+        out blank
+
+        loop do
+          $stdout.print cyan("    key=value › ")
+          raw = $stdin.gets.to_s.strip
+          break if raw.empty?
+
+          unless raw.include?("=")
+            out line(yellow("    Use key=value format (e.g. platform=mobile). Skipping."))
+            next
+          end
+
+          key, value = raw.split("=", 2)
+
+          next out line(yellow("    Use key=value format.")) if key.nil? || key.strip.empty?
+
+          k = key.strip
+          v = (value || "").strip
+          @cfg[:default_meta][k] = v
+          out line(green("    ✓  #{k}: #{v.inspect}"))
+        end
+      end
+
+      def step_serializer
+        out section("Custom Serializer")
+        out line("  By default Respondo serializes ActiveRecord models, collections,")
+        out line("  hashes, and arrays automatically.")
+        out blank
+        out line("  You can override with any callable: ->(obj) { MySerializer.new(obj).as_json }")
+        out blank
+        @cfg[:custom_serializer] = confirm("  Add a custom serializer stub? (y/n) ")
+      end
+
+      # =========================================================================
+      # Summary
+      # =========================================================================
+
+      def print_summary
+        out blank
+        out divider
+        out line(cyan("  Configuration Summary"))
+        out divider
+        out blank
+        summary_row "Project",            @cfg[:project_name]
+        summary_row "API version",        @cfg[:api_version]
+        summary_row "Success message",    @cfg[:default_success_message]
+        summary_row "Error message",      @cfg[:default_error_message]
+        summary_row "Include request_id", @cfg[:include_request_id]
+        summary_row "Camelize keys",      @cfg[:camelize_keys]
+        summary_row "Custom serializer",  @cfg[:custom_serializer]
+
+        unless @cfg[:default_meta].empty?
+          out blank
+          out line("  Global meta:")
+          @cfg[:default_meta].each { |k, v| out line("    #{k}: #{v.inspect}") }
+        end
+
+        out blank
+        out divider
+        out blank
+      end
+
+      def summary_row(label, value)
+        bool_true = value == true
+        val_str   = bool_true ? green(value.inspect) : yellow(value.inspect)
+        out "  #{("#{label}:").ljust(24)}#{val_str}\n"
+      end
+
+      # =========================================================================
+      # Write file
+      # =========================================================================
+
+      def write_initializer
+        dir  = File.join(destination_root, "config", "initializers")
+        path = File.join(dir, "respondo.rb")
+        FileUtils.mkdir_p(dir)
+        File.write(path, build_content)
+        out line(green("  ✅  Created config/initializers/respondo.rb"))
+        out blank
+      end
+
+      def build_content
+        meta = { "api_version" => @cfg[:api_version] }.merge(@cfg[:default_meta])
+        b    = Lines.new
+
+        b << "# frozen_string_literal: true"
+        b << ""
+        b << "# Respondo initializer — #{@cfg[:project_name]}"
+        b << "# Generated by: rails generate respondo:install"
+        b << "# Respondo version: #{Respondo::VERSION}"
+        b << "# Docs: https://github.com/your-org/respondo"
+        b << ""
+        b << "Respondo.configure do |config|"
+        b << ""
+        b << "  # ── Messages ─────────────────────────────────────────────────────────"
+        b << "  # Fallback when render_success / render_error is called without message:"
+        b << "  config.default_success_message = #{@cfg[:default_success_message].inspect}"
+        b << "  config.default_error_message   = #{@cfg[:default_error_message].inspect}"
+        b << ""
+        b << "  # ── Request ID ───────────────────────────────────────────────────────"
+        b << "  # Includes Rails request.request_id in every response meta block."
+        b << "  config.include_request_id = #{@cfg[:include_request_id]}"
+        b << ""
+        b << "  # ── Key Format ───────────────────────────────────────────────────────"
+        b << "  # CamelCase all JSON keys — recommended for Flutter / JS clients."
+        b << "  config.camelize_keys = #{@cfg[:camelize_keys]}"
+        b << ""
+        b << "  # ── Global Meta ──────────────────────────────────────────────────────"
+        b << "  # Static fields merged into the meta block of every response."
+
+        if meta.empty?
+          b << "  config.default_meta = {}"
+        else
+          b << "  config.default_meta = {"
+          meta.each_with_index do |(k, v), i|
+            comma = i < meta.size - 1 ? "," : ""
+            b << "    #{k}: #{v.inspect}#{comma}"
+          end
+          b << "  }"
+        end
+
+        if @cfg[:custom_serializer]
+          b << ""
+          b << "  # ── Custom Serializer ────────────────────────────────────────────────"
+          b << "  # Replace the lambda body with your own serialization logic."
+          b << "  # Examples:"
+          b << "  #   ActiveModelSerializers: ->(obj) { SomeSerializer.new(obj).as_json }"
+          b << "  #   Blueprinter:            ->(obj) { UserBlueprint.render_as_hash(obj) }"
+          b << "  #"
+          b << "  # config.serializer = ->(obj) { MySerializer.new(obj).as_json }"
+        end
+
+        b << ""
+        b << "end"
+        b << ""
+        b.to_s
+      end
+
+      # =========================================================================
+      # Done
+      # =========================================================================
+
+      def print_done
+        out divider
+        out blank
+        out line(cyan("  🎉  Respondo is ready!"))
+        out blank
+        out line("  Next steps:")
+        out line("    1. Review   config/initializers/respondo.rb")
+        out line("    2. Use      render_success / render_error in your controllers")
+        out line("    3. Re-run   rails generate respondo: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"
+      def blank     = "\n"
+
+      def divider
+        "  #{cyan("─" * 68)}\n"
+      end
+
+      def section(title)
+        dashes = "─" * [0, 54 - title.length].max
+        "\n  #{cyan("┌─ #{title} #{dashes}┐")}\n\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
+
+      # =========================================================================
+      # ANSI colors
+      # =========================================================================
+
+      def cyan(t)   = "\e[36m#{t}\e[0m"
+      def green(t)  = "\e[32m#{t}\e[0m"
+      def yellow(t) = "\e[33m#{t}\e[0m"
+
+      # =========================================================================
+      # ASCII logo
+      # =========================================================================
+
+      LOGOS = <<~'LOGO'
+
+          ██████╗ ███████╗███████╗██████╗  ██████╗ ███╗   ██╗██████╗  ██████╗
+          ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔═══██╗████╗  ██║██╔══██╗██╔═══██╗
+          ██████╔╝█████╗  ███████╗██████╔╝██║   ██║██╔██╗ ██║██║  ██║██║   ██║
+          ██╔══██╗██╔══╝  ╚════██║██╔═══╝ ██║   ██║██║╚██╗██║██║  ██║██║   ██║
+          ██║  ██║███████╗███████║██║     ╚██████╔╝██║ ╚████║██████╔╝╚██████╔╝
+          ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝      ╚═════╝ ╚═╝  ╚═══╝╚═════╝  ╚═════╝
+
+                        Smart JSON API Response Formatter for Rails
+                                     ─── v#{Respondo::VERSION} ───
+
+      LOGO
+
+      def logo_with_version
+        green(<<~LOGO)
+          
+          ██████╗ ███████╗███████╗██████╗  ██████╗ ███╗   ██╗██████╗  ██████╗
+          ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔═══██╗████╗  ██║██╔══██╗██╔═══██╗
+          ██████╔╝█████╗  ███████╗██████╔╝██║   ██║██╔██╗ ██║██║  ██║██║   ██║
+          ██╔══██╗██╔══╝  ╚════██║██╔═══╝ ██║   ██║██║╚██╗██║██║  ██║██║   ██║
+          ██║  ██║███████╗███████║██║     ╚██████╔╝██║ ╚████║██████╔╝╚██████╔╝
+          ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝      ╚═════╝ ╚═╝  ╚═══╝╚═════╝  ╚═════╝
+
+                      Smart JSON API Response Formatter for Rails
+                                ─── v#{Respondo::VERSION} ───
+
+        LOGO
+      end
+      # =========================================================================
+      # Simple line buffer for building file content
+      # =========================================================================
+
+      class Lines
+        def initialize = (@buf = [])
+        def <<(str)    = @buf << str
+        def to_s       = @buf.join("\n") + "\n"
+      end
+    end
+  end
+end

data/lib/respondo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Respondo
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/respondo.gemspec

@@ -19,11 +19,20 @@ Gem::Specification.new do |spec|
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 2.7.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}/auditron/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
   spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE.txt", "CHANGELOG.md", "respondo.gemspec"]
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "rspec",        "~> 3.12"
-  spec.add_development_dependency "rake",         "~> 13.0"
-  spec.add_development_dependency "activesupport","~> 7.0"
-  spec.add_development_dependency 'simplecov', '~> 0.22'
+  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

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: respondo
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - shailendra Kumar
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-08 00:00:00.000000000 Z
+date: 2026-04-13 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
@@ -44,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: 8.1.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: 8.1.3
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -80,10 +94,10 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/generators/respondo/install/install_generator.rb
 - lib/respondo.rb
 - lib/respondo/configuration.rb
 - lib/respondo/controller_helpers.rb
-- lib/respondo/pagination.rb
 - lib/respondo/railtie.rb
 - lib/respondo/response_builder.rb
 - lib/respondo/serializer.rb
@@ -92,7 +106,12 @@ files:
 homepage: https://github.com/spatelpatidar/respondo
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/spatelpatidar/respondo
+  source_code_uri: https://github.com/spatelpatidar/respondo
+  changelog_uri: https://github.com/spatelpatidar/respondo/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/spatelpatidar/respondo/auditron/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/respondo/pagination.rb

@@ -1,152 +0,0 @@
-# # frozen_string_literal: true
-
-# module Respondo
-#   # Extracts pagination metadata from Kaminari, Pagy, or WillPaginate collections.
-#   #
-#   # --- How pagination works in Respondo ---
-#   #
-#   # Respondo does NOT paginate data for you. Pagination is always performed by
-#   # your chosen library (Kaminari, Pagy, or WillPaginate) in your controller
-#   # BEFORE you call render_success / render_ok.
-#   #
-#   # Respondo's role is purely to DETECT that the collection is paginated and
-#   # EXTRACT the metadata so it appears in the `meta.pagination` block.
-#   #
-#   # --- Usage patterns by library ---
-#   #
-#   # Kaminari (pagination lives on the collection itself):
-#   #   @users = User.page(params[:page]).per(params[:per_page] || 10)
-#   #   render_ok(data: @users)          # ← just pass the collection; Respondo detects Kaminari
-#   #
-#   # WillPaginate (same — pagination lives on the collection):
-#   #   @users = User.paginate(page: params[:page], per_page: 10)
-#   #   render_ok(data: @users)          # ← same pattern
-#   #
-#   # Pagy (metadata lives on a SEPARATE Pagy object, not the collection):
-#   #   @pagy, @users = pagy(User.all, items: 10)
-#   #   render_ok(data: @users, pagy: @pagy)   # ← pass the Pagy object explicitly
-#   #
-#   #   Alternatively, if you decorate your collection with pagy_metadata:
-#   #   render_ok(data: @pagy)           # ← pass the Pagy object as data (unusual)
-#   #
-#   # --- Returned hash shape (same regardless of library) ---
-#   #   {
-#   #     current_page:  Integer,
-#   #     per_page:      Integer,
-#   #     total_pages:   Integer,
-#   #     total_count:   Integer,
-#   #     next_page:     Integer | nil,
-#   #     prev_page:     Integer | nil
-#   #   }
-#   #
-#   # --- Disabling pagination meta ---
-#   # Pass pagination: false to any render_* helper to suppress the block entirely:
-#   #   render_ok(data: @users, pagination: false)
-#   #
-#   module Pagination
-#     module_function
-
-#     # @param collection [Object] any object — returns nil if not a paginated collection
-#     # @return [Hash, nil]
-#     def extract(collection)
-#       return nil if collection.nil?
-
-#       if pagy?(collection)
-#         from_pagy(collection)
-#       elsif kaminari?(collection)
-#         from_kaminari(collection)
-#       elsif will_paginate?(collection)
-#         from_will_paginate(collection)
-#       else
-#         nil
-#       end
-#     end
-
-#     private
-
-#     module_function
-
-#     # -------------------------------------------------------------------------
-#     # Pagy
-#     # -------------------------------------------------------------------------
-#     # Pagy stores metadata on a SEPARATE Pagy object, not the collection.
-#     # You must pass it explicitly via the `pagy:` keyword in render_success/render_ok.
-#     #
-#     # Example in controller:
-#     #   @pagy, @records = pagy(User.all, items: 10)
-#     #   render_ok(data: @records, pagy: @pagy)
-#     #
-#     def pagy?(object)
-#       defined?(Pagy) && object.is_a?(Pagy)
-#     end
-
-#     def from_pagy(pagy)
-#       {
-#         current_page: pagy.page,
-#         per_page:     pagy.items,
-#         total_pages:  pagy.pages,
-#         total_count:  pagy.count,
-#         next_page:    pagy.next,
-#         prev_page:    pagy.prev
-#       }
-#     end
-
-#     # -------------------------------------------------------------------------
-#     # Kaminari
-#     # -------------------------------------------------------------------------
-#     # Kaminari attaches pagination directly to the ActiveRecord relation.
-#     # No extra argument needed — just pass the collection.
-#     #
-#     # Example in controller:
-#     #   @records = User.page(params[:page]).per(10)
-#     #   render_ok(data: @records)
-#     #
-#     def kaminari?(object)
-#       object.respond_to?(:current_page) &&
-#         object.respond_to?(:total_pages) &&
-#         object.respond_to?(:limit_value)
-#     end
-
-#     def from_kaminari(collection)
-#       {
-#         current_page: collection.current_page,
-#         per_page:     collection.limit_value,
-#         total_pages:  collection.total_pages,
-#         total_count:  collection.total_count,
-#         next_page:    collection.next_page,
-#         prev_page:    collection.prev_page
-#       }
-#     end
-
-#     # -------------------------------------------------------------------------
-#     # WillPaginate
-#     # -------------------------------------------------------------------------
-#     # WillPaginate also attaches pagination to the collection.
-#     # No extra argument needed — just pass the collection.
-#     #
-#     # Example in controller:
-#     #   @records = User.paginate(page: params[:page], per_page: 10)
-#     #   render_ok(data: @records)
-#     #
-#     # We distinguish WillPaginate from Kaminari by the absence of #limit_value.
-#     #
-#     def will_paginate?(object)
-#       object.respond_to?(:current_page) &&
-#         object.respond_to?(:total_pages) &&
-#         object.respond_to?(:per_page) &&
-#         !object.respond_to?(:limit_value)
-#     end
-
-#     def from_will_paginate(collection)
-#       {
-#         current_page: collection.current_page,
-#         per_page:     collection.per_page,
-#         total_pages:  collection.total_pages,
-#         total_count:  collection.total_entries,
-#         next_page:    collection.next_page,
-#         prev_page:    collection.previous_page
-#       }
-#     end
-#   end
-# end
-