respondo 0.1.0

data/lib/respondo/controller_helpers.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Respondo
+  # Mixed into Rails controllers to provide render_success and render_error.
+  #
+  # Success helpers (2xx):
+  #   render_success, render_created, render_accepted, render_no_content,
+  #   render_partial_content, render_multi_status
+  #
+  # Client error helpers (4xx):
+  #   render_bad_request, render_unauthorized, render_payment_required,
+  #   render_forbidden, render_not_found, render_method_not_allowed,
+  #   render_not_acceptable, render_conflict, render_gone,
+  #   render_unprocessable, render_too_many_requests, render_locked,
+  #   render_precondition_failed, render_unsupported_media_type,
+  #   render_request_timeout
+  #
+  # Server error helpers (5xx):
+  #   render_server_error, render_not_implemented, render_bad_gateway,
+  #   render_service_unavailable, render_gateway_timeout
+  module ControllerHelpers
+
+    # =========================================================================
+    # Core DSL — all helpers delegate to these two
+    # =========================================================================
+
+    # Render a successful JSON response.
+    #
+    # @param data       [Object]          payload — AR model, collection, Hash, Array, nil
+    # @param message    [String]          human-readable description
+    # @param meta       [Hash]            extra meta fields merged into the meta block
+    # @param pagy       [Pagy]            optional Pagy object (pass when using Pagy backend)
+    # @param pagination [Boolean]         true  = include pagination meta when available (default)
+    #                                     false = always suppress pagination meta
+    # @param status     [Symbol, Integer] HTTP status (default: :ok / 200)
+    def render_success(data: nil, message: nil, meta: {}, code: nil, pagy: nil, pagination: true, status: :ok)
+      merged_meta  = code ? meta.merge(code: code, status: status) : meta
+
+      payload = ResponseBuilder.new(
+        success:    true,
+        data:       data,
+        message:    message,
+        meta:       merged_meta,
+        pagy:       pagy,
+        pagination: pagination,
+        request:    try(:request)
+      ).build
+
+      render json: payload, status: status
+    end
+
+    # Render an error JSON response.
+    #
+    # @param message [String]                      human-readable error description
+    # @param errors  [Hash, ActiveModel::Errors]   field-level validation errors
+    # @param code    [String, nil]                 machine-readable error code e.g. "AUTH_EXPIRED"
+    # @param meta    [Hash]                        extra meta fields
+    # @param status  [Symbol, Integer]             HTTP status (default: :unprocessable_entity / 422)
+
+    def render_error(message: nil, errors: nil, code: nil, meta: {}, status: :unprocessable_entity)
+      extracted_errors = extract_errors(errors)
+      merged_meta      = code ? meta.merge(code: code, status: status) : meta
+
+      payload = ResponseBuilder.new(
+        success:    false,
+        data:       nil,
+        message:    message,
+        meta:       merged_meta,
+        errors:     extracted_errors,
+        pagination: false,
+        request:    try(:request)
+      ).build
+
+      render json: payload, status: status
+    end
+
+    # =========================================================================
+    # 2xx Success helpers
+    # =========================================================================
+
+    # 200 OK — alias for render_success with no pagination (single record)
+    def render_ok(data: nil, message: nil, meta: {}, pagination: true)
+      render_success(data: data, message: message, meta: meta, pagination: pagination, code:200, status: :ok)
+    end
+
+    # 201 Created
+    def render_created(data: nil, message: "Created successfully", pagination: false)
+      render_success(data: data, message: message, pagination: pagination, code:201, status: :created)
+    end
+
+    # 202 Accepted — async jobs, background processing
+    def render_accepted(data: nil, message: "Request accepted and is being processed")
+      render_success(data: data, message: message, pagination: false, code:202, status: :accepted)
+    end
+
+    # 204 No Content — deletions, actions with no response body
+    # Note: we still return our standard JSON structure for consistency
+    def render_no_content(message: "Deleted successfully")
+      render_success(data: nil, message: message, pagination: false, code:204, status: :ok)
+    end
+
+    # 206 Partial Content — chunked / range responses
+    def render_partial_content(data: nil, message: "Partial content returned", meta: {})
+      render_success(data: data, message: message, meta: meta, pagination: false, code:206, status: :partial_content)
+    end
+
+    # 207 Multi-Status — batch operations with mixed results
+    def render_multi_status(data: nil, message: "Multi-status response", meta: {})
+      render_success(data: data, message: message, meta: meta, pagination: false, code:207, status: :multi_status)
+    end
+
+    # =========================================================================
+    # 4xx Client error helpers
+    # =========================================================================
+
+    # 400 Bad Request — malformed request, invalid params
+    def render_bad_request(message: "Bad request", errors: nil, code: "BAD_REQUEST")
+      render_error(message: message, errors: errors, code: code, status: :bad_request)
+    end
+
+    # 401 Unauthorized — not authenticated
+    def render_unauthorized(message: "Unauthorized", errors: nil, code: "UNAUTHORIZED")
+      render_error(message: message, errors: errors, code: code, status: :unauthorized)
+    end
+
+    # 402 Payment Required — paywalled features
+    def render_payment_required(message: "Payment required to access this resource", errors: nil, code: "PAYMENT_REQUIRED")
+      render_error(message: message, errors: errors, code: code, status: :payment_required)
+    end
+
+    # 403 Forbidden — authenticated but not authorized
+    def render_forbidden(message: "You do not have permission to perform this action", errors: nil, code: "FORBIDDEN")
+      render_error(message: message, errors: errors, code: code, status: :forbidden)
+    end
+
+    # 404 Not Found
+    def render_not_found(message: "Resource not found", errors: nil, code: "NOT_FOUND")
+      render_error(message: message, errors: errors, code: code, status: :not_found)
+    end
+
+    # 405 Method Not Allowed
+    def render_method_not_allowed(message: "HTTP method not allowed", errors: nil, code: "METHOD_NOT_ALLOWED")
+      render_error(message: message, errors: errors, code: code, status: :method_not_allowed)
+    end
+
+    # 406 Not Acceptable — client Accept header can't be satisfied
+    def render_not_acceptable(message: "Requested format not acceptable", errors: nil, code: "NOT_ACCEPTABLE")
+      render_error(message: message, errors: errors, code: code, status: :not_acceptable)
+    end
+
+    # 408 Request Timeout
+    def render_request_timeout(message: "Request timed out", errors: nil, code: "REQUEST_TIMEOUT")
+      render_error(message: message, errors: errors, code: code, status: :request_timeout)
+    end
+
+    # 409 Conflict — duplicate record, state conflict
+    def render_conflict(message: "Resource conflict", errors: nil, code: "CONFLICT")
+      render_error(message: message, errors: errors, code: code, status: :conflict)
+    end
+
+    # 410 Gone — resource permanently deleted
+    def render_gone(message: "Resource no longer available", errors: nil, code: "GONE")
+      render_error(message: message, errors: errors, code: code, status: :gone)
+    end
+
+    # 412 Precondition Failed — conditional request failed
+    def render_precondition_failed(message: "Precondition failed", errors: nil, code: "PRECONDITION_FAILED")
+      render_error(message: message, errors: errors, code: code, status: :precondition_failed)
+    end
+
+    # 415 Unsupported Media Type — wrong Content-Type header
+    def render_unsupported_media_type(message: "Unsupported media type", errors: nil, code: "UNSUPPORTED_MEDIA_TYPE")
+      render_error(message: message, errors: errors, code: code, status: :unsupported_media_type)
+    end
+
+    # 422 Unprocessable Entity — validation errors (most common for APIs)
+    def render_unprocessable(message: "Validation failed", errors: nil, code: "UNPROCESSABLE_ENTITY")
+      render_error(message: message, errors: errors, code: code, status: :unprocessable_entity)
+    end
+
+    # 423 Locked — resource is locked
+    def render_locked(message: "Resource is locked", errors: nil, code: "LOCKED")
+      render_error(message: message, errors: errors, code: code, status: :locked)
+    end
+
+    # 429 Too Many Requests — rate limiting
+    def render_too_many_requests(message: "Too many requests. Please slow down.", errors: nil, code: "RATE_LIMITED")
+      render_error(message: message, errors: errors, code: code, status: :too_many_requests)
+    end
+
+    # =========================================================================
+    # 5xx Server error helpers
+    # =========================================================================
+
+    # 500 Internal Server Error
+    def render_server_error(message: "An unexpected error occurred", errors: nil, code: "SERVER_ERROR")
+      render_error(message: message, errors: errors, code: code, status: :internal_server_error)
+    end
+
+    # 501 Not Implemented — feature not built yet
+    def render_not_implemented(message: "This feature is not yet implemented", errors: nil, code: "NOT_IMPLEMENTED")
+      render_error(message: message, errors: errors, code: code, status: :not_implemented)
+    end
+
+    # 502 Bad Gateway — upstream service failed
+    def render_bad_gateway(message: "Bad gateway — upstream service error", errors: nil, code: "BAD_GATEWAY")
+      render_error(message: message, errors: errors, code: code, status: :bad_gateway)
+    end
+
+    # 503 Service Unavailable — maintenance, overloaded
+    def render_service_unavailable(message: "Service temporarily unavailable", errors: nil, code: "SERVICE_UNAVAILABLE")
+      render_error(message: message, errors: errors, code: code, status: :service_unavailable)
+    end
+
+    # 504 Gateway Timeout — upstream service timed out
+    def render_gateway_timeout(message: "Gateway timeout — upstream service did not respond", errors: nil, code: "GATEWAY_TIMEOUT")
+      render_error(message: message, errors: errors, code: code, status: :gateway_timeout)
+    end
+
+    private
+
+    # Normalize errors into a plain Hash regardless of source type.
+    def extract_errors(errors)
+      return nil if errors.nil?
+
+      if defined?(ActiveModel::Errors) && errors.is_a?(ActiveModel::Errors)
+        return errors.to_hash
+      end
+
+      return errors if errors.is_a?(Hash)
+
+      if errors.is_a?(Array)
+        return { base: errors }
+      end
+
+      if errors.is_a?(String)
+        return { base: [errors] }
+      end
+
+      nil
+    end
+  end
+end

data/lib/respondo/pagination.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Respondo
+  # Extracts pagination metadata from Kaminari or Pagy collection objects.
+  #
+  # Returned hash shape (always the same regardless of pagination library):
+  #   {
+  #     current_page:  Integer,
+  #     per_page:      Integer,
+  #     total_pages:   Integer,
+  #     total_count:   Integer,
+  #     next_page:     Integer | nil,
+  #     prev_page:     Integer | nil
+  #   }
+  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 itself.
+    # We support both: passing the Pagy object directly, or a collection that
+    # has been decorated with pagy metadata via pagy_metadata.
+    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 -----------------------------------------------------------
+    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 -------------------------------------------------------
+    def will_paginate?(object)
+      object.respond_to?(:current_page) &&
+        object.respond_to?(:total_pages) &&
+        object.respond_to?(:per_page) &&
+        !object.respond_to?(:limit_value) # distinguishes from Kaminari
+    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

data/lib/respondo/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Respondo
+  # Railtie automatically includes Respondo::ControllerHelpers into
+  # ActionController::Base and ActionController::API when Rails is present.
+  # No manual include needed in ApplicationController.
+  class Railtie < Rails::Railtie
+    initializer "respondo.include_controller_helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Respondo::ControllerHelpers
+      end
+
+      ActiveSupport.on_load(:action_controller_api) do
+        include Respondo::ControllerHelpers
+      end
+    end
+  end
+end

data/lib/respondo/response_builder.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Respondo
+  # Builds the standardized response hash.
+  #
+  # Every response always contains these top-level keys:
+  #   {
+  #     success: Boolean,
+  #     message: String,
+  #     data:    Object | Array | nil,
+  #     meta:    Hash
+  #   }
+  #
+  # The meta block always contains:
+  #   { timestamp: ISO8601 String }
+  # Plus pagination keys when pagination: true and the data is a paginated collection.
+  # Plus request_id when config.include_request_id is true.
+  class ResponseBuilder
+    # @param success    [Boolean]
+    # @param data       [Object]   anything — serialized automatically
+    # @param message    [String]
+    # @param meta       [Hash]     caller-supplied extra meta (merged in)
+    # @param errors     [Hash]     field-level errors (for 422 responses)
+    # @param pagy       [Pagy]     optional Pagy object for pagination meta
+    # @param pagination [Boolean]  true = include pagination meta (default),
+    #                              false = always suppress pagination meta
+    # @param request    [Object]   ActionDispatch::Request (for request_id)
+    def initialize(success:, data: nil, message: nil, meta: {}, errors: nil,
+                   pagy: nil, pagination: true, request: nil)
+      @success    = success
+      @raw_data   = data
+      @message    = message
+      @extra_meta = meta || {}
+      @errors     = errors
+      @pagy       = pagy
+      @pagination = pagination
+      @request    = request
+    end
+
+    # @return [Hash] the complete response payload
+    def build
+      # We initialize the hash in the exact order we want keys to appear
+      payload = {
+        success: @success,
+        message: resolve_message,
+        data:    serialize_data,
+      }
+
+      # Add errors before meta if they exist
+      payload[:errors] = @errors if @errors && !@errors.empty?
+
+      # Finally, add meta so it appears at the bottom
+      payload[:meta] = build_meta
+
+      apply_camelize(payload)
+    end
+
+    private
+
+    def resolve_message
+      return @message if @message && !@message.empty?
+      @success ? Respondo.config.default_success_message : Respondo.config.default_error_message
+    end
+
+    def serialize_data
+      Serializer.call(@raw_data)
+    end
+
+    def build_meta
+      meta = { timestamp: current_timestamp }
+
+      # Only extract pagination when caller has not explicitly disabled it
+      if @pagination
+        pagination = if @pagy
+          Pagination.extract(@pagy)
+        else
+          Pagination.extract(@raw_data)
+        end
+        meta[:pagination] = pagination if pagination
+      end
+
+      # Request ID (Rails only, opt-in via config)
+      if Respondo.config.include_request_id && @request&.respond_to?(:request_id)
+        meta[:request_id] = @request.request_id
+      end
+
+      # Merge any caller-supplied meta last (allows overriding)
+      meta.merge(@extra_meta)
+    end
+
+    def current_timestamp
+      if defined?(Time.current)
+        Time.current.iso8601
+      else
+        Time.now.utc.iso8601
+      end
+    end
+
+    def apply_camelize(hash)
+      return hash unless Respondo.config.camelize_keys
+      camelize_hash(hash)
+    end
+
+    def camelize_hash(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), memo|
+          memo[camelize_key(k)] = camelize_hash(v)
+        end
+      when Array
+        obj.map { |item| camelize_hash(item) }
+      else
+        obj
+      end
+    end
+
+    def camelize_key(key)
+      key.to_s.gsub(/_([a-z])/) { $1.upcase }.to_sym
+    end
+  end
+end

data/lib/respondo/serializer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Respondo
+  # Responsible for converting any Ruby object into a JSON-safe Hash or Array.
+  #
+  # Priority order:
+  #   1. Custom serializer from Respondo.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 Respondo.config.serializer
+        return Respondo.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/version.rb

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

data/lib/respondo.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "respondo/version"
+require_relative "respondo/configuration"
+require_relative "respondo/serializer"
+require_relative "respondo/pagination"
+require_relative "respondo/response_builder"
+require_relative "respondo/controller_helpers"
+
+# Respondo — Smart JSON API response formatter for Rails.
+#
+# @example Configure once in an initializer
+#   # config/initializers/respondo.rb
+#   Respondo.configure do |config|
+#     config.default_success_message = "OK"
+#     config.default_error_message   = "Something went wrong"
+#     config.include_request_id      = true
+#     config.camelize_keys           = true   # for Flutter/JS clients
+#   end
+#
+# @example Include manually (without Railtie / outside Rails)
+#   class MyController
+#     include Respondo::ControllerHelpers
+#   end
+module Respondo
+  class << self
+    # @return [Respondo::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # @yield [Respondo::Configuration]
+    def configure
+      yield config
+    end
+
+    # Reset config (useful in tests)
+    def reset!
+      @config = Configuration.new
+    end
+  end
+end
+
+# Auto-integrate with Rails if present
+require_relative "respondo/railtie" if defined?(Rails::Railtie)

data/respondo.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/respondo/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "respondo"
+  spec.version       = Respondo::VERSION
+  spec.authors       = ["shailendra Kumar"]
+  spec.email         = ["shailendrapatidar00@gmail.com"]
+
+  spec.summary       = "Smart JSON API response formatter for Rails — consistent structure every time."
+  spec.description   = <<~DESC
+    Respondo standardizes JSON API responses across Rails applications.
+    Every response gets success, data, message, and meta fields.
+    Automatic pagination meta for Kaminari and Pagy collections.
+    ActiveRecord serialization, error extraction, and flexible HTTP codes built in.
+  DESC
+  spec.homepage      = "https://github.com/spatelpatidar/respondo"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  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'
+end