jsonapi_responses 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0699dc3667f281c640290126057003d615a2925420486b95bf4c6b6ca0498493'
-  data.tar.gz: 2ad39e4993c900b4d675fcba5cf45065d7b467a34f06c6e99d7e6a246dc87010
+  metadata.gz: ab50f413d2756f7f1f6b1faae376ebaf041a60fef7df43b29c037cfdfff295c2
+  data.tar.gz: a3921894b3f3c0a3565e4be39667c4c9f643b9837c35c1a1e8c9c1ac491c477d
 SHA512:
-  metadata.gz: c9272215b1f4238ab65d30e961a928d1d20307287e1d3b82a9dbbe79f0f08c63567973e3b38cde93777064f20c8d0d977541910cf2b3433604eef0891a662e3b
-  data.tar.gz: 6b2f625abcbe757534d222f16a1edcbbdd24f1947f5071a6f26c7ad1b2745fe188c51f54d69aaf777124e8af3eacb33a8769a9bc701c3538cf95623fbdc013f7
+  metadata.gz: 0bfebe0f3f65b8125776d5161b7c26ac0d673ae979e8ca84ebca91422ef895812260e857ee43404c5a684eeec2e816258397229d25f172b3b4875d311cd6b979
+  data.tar.gz: 83a0979577818624cabe42b395c12df5c1ea594768a855469ecd9de0673911bc6b6843731020f21931b81da35f8eb83582d9d99f826f19d13cfc52381d3e9955

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 ## [Unreleased]
 
+## [1.1.0] - 2025-11-21
+
+### Added
+
+- **Automatic Pagination Support**: `respond_for_index` now auto-detects Kaminari/WillPaginate pagination and includes meta automatically
+- **Pagination Helpers in Responder**: Added `paginated?`, `pagination_meta`, and `render_collection_with_meta` methods
+- **Smart Meta Handling**: Automatically merges pagination meta with context meta if both are present
+
+### Features
+
+- Auto-detection of paginated collections (checks for `current_page`, `total_pages`, `total_count` methods)
+- Automatic inclusion of pagination metadata: `current_page`, `total_pages`, `total_count`, `per_page`
+- Backward compatible - works with manual `meta` in context or auto-detects pagination
+- Works with both Kaminari and WillPaginate gems
+
+### Example Usage
+
+```ruby
+# Controller - Automatic pagination meta
+def index
+  @academies = Academy.page(params[:page]).per(15)
+  render_with(@academies) # Auto-includes pagination meta!
+end
+
+# Manual meta still works
+def index
+  @academies = Academy.page(params[:page]).per(15)
+  render_with(@academies, context: { meta: { custom: 'data' } })
+  # Merges pagination + custom meta
+end
+
+# Custom responder with pagination helper
+class MyResponder < JsonapiResponses::Responder
+  def render
+    render_collection_with_meta(record, { custom: 'meta' })
+  end
+end
+```
+
 ## [1.0.0] - 2025-10-07
 
 ### 🎉 Major Release - Breaking Changes
@@ -7,11 +46,13 @@
 This is a major release with significant architectural improvements and breaking changes.
 
 ### Breaking Changes
+
 - **Renamed `BaseSerializer`** → `ApplicationSerializer` (follows Rails convention)
 - **Renamed `BaseResponder`** → `ApplicationResponder` (follows Rails convention like ApplicationPolicy)
 - Responders now follow **Pundit-style pattern**: one responder class per controller with multiple action methods
 
 ### Added
+
 - **Pundit-Style Responders**: One responder class per controller (e.g., `AcademyResponder`, `CourseResponder`)
 - **Action-based method calls**: Use `render_with(@records, responder: AcademyResponder, action: :featured)`
 - **ApplicationResponder base class**: With common helpers like `render_collection_with_meta`, `base_meta`, `filters_applied`
@@ -43,7 +84,7 @@ class AcademyResponder < ApplicationResponder
   def featured  # ← Method instead of render
     # ...
   end
-  
+
   def popular
     # ...
   end
@@ -63,6 +104,7 @@ render_with(@academies, responder: AcademyResponder, action: :featured)
 #### 3. Consolidate Responders
 
 Instead of one file per action:
+
 ```
 # Before
 app/responders/academy_featured_responder.rb
@@ -74,7 +116,8 @@ app/responders/academy_responder.rb  # All methods inside
 ```
 
 ### Improved
-- Better alignment with Rails naming conventions (Application* prefix)
+
+- Better alignment with Rails naming conventions (Application\* prefix)
 - Reduced file proliferation (3-4 responder files instead of 20+)
 - Easier to maintain and understand (Pundit-style pattern)
 - Better code organization and discoverability
@@ -82,18 +125,18 @@ app/responders/academy_responder.rb  # All methods inside
 ## [0.3.0] - 2025-10-07
 
 ### Added
+
 - **Custom Responders System**: New architecture for handling complex custom actions
   - Added `JsonapiResponses::Responder` base class for creating dedicated responder objects
   - Responders encapsulate response logic, keeping controllers clean and promoting reusability
   - Full access to controller context, serialization helpers, and request params
-  
 - **Responder Base Class Features**:
   - `serialize_collection` and `serialize_item` helpers for data serialization
   - `render_json` helper for consistent JSON rendering
   - `collection?` and `single_item?` type checking utilities
   - Access to `params`, `current_user`, `controller`, `record`, `serializer_class`, and `context`
-  
 - **Enhanced render_with**:
+
   - New `responder:` parameter to use custom responder classes
   - New `serializer:` parameter to override default serializer detection
   - Example: `render_with(@records, responder: FeaturedResponder, serializer: CustomSerializer)`
@@ -104,17 +147,20 @@ app/responders/academy_responder.rb  # All methods inside
   - `CategorizedResponder` - For grouped/categorized responses
 
 ### Changed
+
 - Updated `lib/jsonapi_responses.rb` to require `responder.rb`
 - Enhanced `Respondable` module to support responder classes
 - Improved documentation with comprehensive Responder guide
 
 ### Documentation
+
 - Added "Custom Responders" section to README with complete examples
 - Added comparison table: when to use each approach (mapping vs methods vs responders)
 - Added `RESPONDERS_FEATURE.md` with complete implementation guide
 - Documented Responder API and best practices
 
 ### Benefits
+
 - **Separation of Concerns**: Response logic separated from controllers
 - **Reusability**: Same responder can be used across multiple controllers
 - **Testability**: Test response logic independently from controllers
@@ -123,31 +169,35 @@ app/responders/academy_responder.rb  # All methods inside
 ## [0.2.0] - 2025-10-06
 
 ### Added
+
 - **Custom Actions Support**: Support for custom actions beyond standard CRUD (index, show, create, update, destroy)
 - **Explicit Action Mapping**: `map_response_action` and `map_response_actions` for mapping custom actions to existing responses
 - **Metaprogramming Support**: Dynamic method generation for response handlers
   - `define_response_for`: Define custom response methods using blocks
   - `define_responses_for`: Define same behavior for multiple actions in batch
   - `define_crud_responses`: Intelligent CRUD responses with dynamic context
-  - `generate_rest_responses`: Auto-generate namespaced REST responses (public_, admin_, etc.)
+  - `generate_rest_responses`: Auto-generate namespaced REST responses (public*, admin*, etc.)
 - **Dynamic Context**: Support for lambdas/procs in context generation with `instance_eval`
 - **Method Introspection**: `response_definitions` class attribute for debugging generated methods
 - **Enhanced Error Messages**: Detailed error responses with suggestions when actions are not supported
 
 ### Changed
+
 - **Breaking**: Removed automatic fallback behavior for action mapping (by design - explicit is better than implicit)
 - **Improved**: `render_invalid_action` now provides detailed error information with actionable suggestions
 - **Enhanced**: Better error handling with specific guidance on how to implement missing methods
 
 ### Technical Details
+
 - Added `class_attribute :response_definitions` for storing method definitions
 - Enhanced `render_with` method resolution to support custom and mapped actions
 - All generated methods are properly marked as private
 - Full backward compatibility maintained for existing CRUD operations
 
 ### Documentation
+
 - Added comprehensive documentation in CUSTOM_ACTIONS.md
-- Added metaprogramming guide in METAPROGRAMMING.md  
+- Added metaprogramming guide in METAPROGRAMMING.md
 - Added practical implementation example in PRACTICAL_EXAMPLE.md
 - Updated README with new functionality overview
 

data/README.md

@@ -147,11 +147,160 @@ GET /api/v1/digital_products?view=minimal  # Returns minimal response
 ### Performance Benefits
 
 By allowing the frontend to request only the needed data, you can:
+
 - Reduce response payload size
 - Improve API performance
 - Avoid creating multiple endpoints for different data requirements
 - Optimize database queries based on the requested view
 
+## Automatic Pagination Support
+
+**New in v1.1.0:** JsonapiResponses now automatically detects and handles paginated collections using Kaminari, making pagination effortless.
+
+### Basic Usage
+
+When you paginate your records with Kaminari, pagination metadata is automatically included in the response:
+
+```ruby
+class Api::V1::AcademiesController < ApplicationController
+  include JsonapiResponses::Respondable
+
+  def index
+    academies = Academy.page(params[:page]).per(15)
+    
+    # That's it! Pagination is automatic
+    render_with(academies)
+  end
+end
+```
+
+**Response:**
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "Academy 1", ... },
+    { "id": 2, "name": "Academy 2", ... }
+  ],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 5,
+    "total_count": 73,
+    "per_page": 15
+  }
+}
+```
+
+### How It Works
+
+JsonapiResponses automatically detects if your collection responds to Kaminari's pagination methods:
+- `current_page`
+- `total_pages`
+- `total_count`
+
+If these methods exist, pagination metadata is automatically included in the response.
+
+### With Custom Views
+
+Pagination works seamlessly with different view formats:
+
+```ruby
+def index
+  academies = Academy
+    .includes(:owner, :courses)
+    .page(params[:page])
+    .per(params[:per_page] || 15)
+  
+  # Supports view parameter and automatic pagination
+  render_with(academies)
+end
+```
+
+**Request:**
+```
+GET /api/v1/academies?page=2&per_page=20&view=summary
+```
+
+**Response:**
+```json
+{
+  "data": [
+    { "id": 21, "name": "Academy 21", ... }
+  ],
+  "meta": {
+    "current_page": 2,
+    "total_pages": 4,
+    "total_count": 73,
+    "per_page": 20
+  }
+}
+```
+
+### Requirements
+
+- **Kaminari gem** must be installed and configured
+- Your collection must be paginated with `.page()` method
+
+### Custom Pagination Metadata
+
+You can add additional metadata alongside automatic pagination:
+
+```ruby
+def index
+  academies = Academy.page(params[:page]).per(15)
+  
+  render_with(
+    academies,
+    context: { view: view },
+    meta: { 
+      fetched_at: Time.current,
+      filters_applied: params[:search].present?
+    }
+  )
+end
+```
+
+**Response:**
+```json
+{
+  "data": [...],
+  "meta": {
+    "current_page": 1,
+    "total_pages": 5,
+    "total_count": 73,
+    "per_page": 15,
+    "fetched_at": "2024-01-15T10:30:00Z",
+    "filters_applied": true
+  }
+}
+```
+
+### Using Pagination Helpers
+
+For custom responders, use the built-in pagination helpers:
+
+```ruby
+class AcademyResponder < JsonapiResponses::Responder
+  def respond_for_index
+    if paginated?(record)
+      render json: {
+        data: serialize_collection(record, serializer_class, context),
+        meta: pagination_meta(record, context)
+      }
+    else
+      render json: {
+        data: serialize_collection(record, serializer_class, context)
+      }
+    end
+  end
+end
+```
+
+Available helpers:
+- `paginated?(record)` - Check if record supports pagination
+- `pagination_meta(record, context)` - Extract pagination metadata hash
+- `render_collection_with_meta(record, serializer_class, context)` - Render with automatic pagination
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -165,14 +314,15 @@ Beyond the standard CRUD actions (index, show, create, update, destroy), you can
 ### Basic Usage
 
 **Option 1: Map to existing actions**
+
 ```ruby
 class Api::V1::CoursesController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   # Map custom actions to existing response methods
   map_response_action :public_index, to: :index
   map_response_action :public_show, to: :show
-  
+
   def public_index
     # Your logic here
     render_with(@courses)  # Will use respond_for_index
@@ -181,17 +331,18 @@ end
 ```
 
 **Option 2: Define custom response methods**
+
 ```ruby
 class Api::V1::CoursesController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   def dashboard_stats
     # Your logic here
     render_with(@stats)
   end
-  
+
   private
-  
+
   def respond_for_dashboard_stats(record, serializer_class, context)
     render json: {
       data: record,
@@ -202,17 +353,18 @@ end
 ```
 
 **Option 3: Metaprogramming (Recommended for complex scenarios)**
+
 ```ruby
 class Api::V1::CoursesController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   # Generate methods automatically
   generate_rest_responses(
     namespace: 'public',
     actions: [:index, :show],
     context: { access_level: 'public' }
   )
-  
+
   # Define similar responses in batch
   define_responses_for [:export_csv, :export_pdf] do |record, serializer_class, context|
     format = action_name.to_s.split('_').last
@@ -253,26 +405,26 @@ app/responders/
 # app/responders/application_responder.rb
 class ApplicationResponder < JsonapiResponses::Responder
   protected
-  
+
   def render_collection_with_meta(type: nil, additional_meta: {})
     render_json({
       data: serialize_collection(record),
       meta: base_meta.merge({ type: type }.compact).merge(additional_meta)
     })
   end
-  
+
   def base_meta
     {
       timestamp: Time.current.iso8601,
       count: record_count
     }.compact
   end
-  
+
   def record_count
     return nil unless collection?
     record.respond_to?(:count) ? record.count : record.size
   end
-  
+
   def filters_applied
     filter_keys = [:category_id, :level, :status]
     filters = {}
@@ -287,7 +439,7 @@ end
 ```ruby
 # app/responders/academy_responder.rb
 class AcademyResponder < ApplicationResponder
-  
+
   # GET /api/v1/academies/featured
   def featured
     if params[:category_id].present?
@@ -296,7 +448,7 @@ class AcademyResponder < ApplicationResponder
       render_all_featured
     end
   end
-  
+
   # GET /api/v1/academies/popular
   def popular
     render_collection_with_meta(
@@ -307,7 +459,7 @@ class AcademyResponder < ApplicationResponder
       }
     )
   end
-  
+
   # GET /api/v1/academies/recommended
   def recommended
     render_collection_with_meta(
@@ -318,9 +470,9 @@ class AcademyResponder < ApplicationResponder
       }
     )
   end
-  
+
   private
-  
+
   def render_filtered_featured
     render_json({
       data: serialize_collection(record),
@@ -330,7 +482,7 @@ class AcademyResponder < ApplicationResponder
       }
     })
   end
-  
+
   def render_all_featured
     render_collection_with_meta(type: 'featured')
   end
@@ -347,12 +499,12 @@ class Api::V1::AcademiesController < ApplicationController
     @academies = load_featured_academies
     render_with(@academies, responder: AcademyResponder, action: :featured)
   end
-  
+
   def popular
     @academies = Academy.popular.limit(20)
     render_with(@academies, responder: AcademyResponder, action: :popular)
   end
-  
+
   def recommended
     @academies = Academy.recommended_for(current_user)
     render_with(@academies, responder: AcademyResponder, action: :recommended)
@@ -363,12 +515,14 @@ end
 ### Benefits of This Pattern
 
 **Like Pundit Policies:**
+
 - ✅ One file per controller (not per action)
 - ✅ All related logic in one place
 - ✅ Easy to find and maintain
 - ✅ Shared helpers in base class
 
 **Example Structure:**
+
 ```
 AcademiesController → AcademyResponder (featured, popular, recommended)
 CoursesController   → CourseResponder (featured, search, progress)
@@ -384,18 +538,18 @@ class MyCustomResponder < JsonapiResponses::Responder
   def render
     # Access to controller instance
     controller.current_user
-    
+
     # Access to params
     params[:filter]
-    
+
     # Serialize data
     serialize_collection(record)  # For collections
     serialize_item(record)         # For single items
-    
+
     # Check record type
     collection?    # true if record is a collection
     single_item?   # true if record is a single item
-    
+
     # Render JSON
     render_json({ data: [], meta: {} })
   end
@@ -419,14 +573,14 @@ class CategorizedResponder < JsonapiResponses::Responder
   private
 
   def structured_data?
-    record.is_a?(Array) && 
-    record.first.is_a?(Hash) && 
+    record.is_a?(Array) &&
+    record.first.is_a?(Hash) &&
     record.first.key?(:category)
   end
 
   def group_by_category
     categories = {}
-    
+
     serialize_collection(record).each do |item|
       category_id = item.dig(:category, :id) || 'uncategorized'
       categories[category_id] ||= {
@@ -435,7 +589,7 @@ class CategorizedResponder < JsonapiResponses::Responder
       }
       categories[category_id][:items] << item
     end
-    
+
     categories.values.map do |group|
       group.merge(count: group[:items].size)
     end
@@ -445,12 +599,12 @@ end
 
 ### When to Use Each Approach
 
-| Approach | Best For | Complexity |
-|----------|----------|------------|
-| `map_response_action` | Simple actions similar to existing ones | Low |
-| `respond_for_*` methods | 1-2 custom actions with simple logic | Medium |
-| Custom Responders | 3+ custom actions or complex response logic | High |
-| Metaprogramming | Batch generation of similar actions | High |
+| Approach                | Best For                                    | Complexity |
+| ----------------------- | ------------------------------------------- | ---------- |
+| `map_response_action`   | Simple actions similar to existing ones     | Low        |
+| `respond_for_*` methods | 1-2 custom actions with simple logic        | Medium     |
+| Custom Responders       | 3+ custom actions or complex response logic | High       |
+| Metaprogramming         | Batch generation of similar actions         | High       |
 
 ### Mixing Approaches
 
@@ -459,23 +613,23 @@ You can combine different approaches in the same controller:
 ```ruby
 class Api::V1::ProductsController < ApplicationController
   include JsonapiResponses::Respondable
-  
+
   # Map simple actions
   map_response_action :public_index, to: :index
-  
+
   # Use responder for complex actions
   def featured
     @products = Product.featured
     render_with(@products, responder: FeaturedResponder)
   end
-  
+
   # Use custom method for one-off logic
   def statistics
     render_with(@stats)
   end
-  
+
   private
-  
+
   def respond_for_statistics(record, serializer_class, context)
     render json: { stats: record, generated_at: Time.current }
   end

data/app/responders/application_responder.rb

@@ -0,0 +1,99 @@
+# ApplicationResponder - Base class for all responders
+# 
+# This follows Rails convention (like ApplicationRecord, ApplicationController)
+# and Pundit pattern (like ApplicationPolicy).
+#
+# Create one responder per controller with multiple action methods inside.
+#
+# @example Creating a resource responder
+#   class ProductResponder < ApplicationResponder
+#     # GET /products/featured
+#     def featured
+#       render_collection_with_meta(
+#         type: 'featured',
+#         additional_meta: { category: params[:category_id] }
+#       )
+#     end
+#     
+#     # GET /products/popular
+#     def popular
+#       render_collection_with_meta(
+#         type: 'popular',
+#         additional_meta: { period: params[:period] || 'month' }
+#       )
+#     end
+#   end
+#
+# @example Using in controller
+#   class ProductsController < ApplicationController
+#     def featured
+#       @products = Product.featured
+#       render_with(@products, responder: ProductResponder, action: :featured)
+#     end
+#   end
+class ApplicationResponder < JsonapiResponses::Responder
+  # Common helper methods available to all responders
+  
+  protected
+  
+  # Render a standard collection with metadata
+  # @param type [String, Symbol] Type of collection (e.g., 'featured', 'popular')
+  # @param additional_meta [Hash] Additional metadata to include
+  def render_collection_with_meta(type: nil, additional_meta: {})
+    render_json({
+      data: serialize_collection(record),
+      meta: base_meta.merge({ type: type }.compact).merge(additional_meta)
+    })
+  end
+  
+  # Render a single item with metadata
+  # @param additional_meta [Hash] Additional metadata to include
+  def render_item_with_meta(additional_meta: {})
+    render_json({
+      data: serialize_item(record),
+      meta: base_meta.merge(additional_meta)
+    })
+  end
+  
+  # Render grouped/categorized data
+  # @param groups [Array, Hash] Pre-structured grouped data
+  def render_grouped_data(groups)
+    render_json(groups)
+  end
+  
+  # Base metadata common to all responses
+  # @return [Hash] Base metadata including timestamp and count
+  def base_meta
+    {
+      timestamp: Time.current.iso8601,
+      count: record_count
+    }.compact
+  end
+  
+  # Get the count of records
+  # @return [Integer, nil] Count if collection, nil otherwise
+  def record_count
+    return nil unless collection?
+    record.respond_to?(:count) ? record.count : record.size
+  end
+  
+  # Check if a parameter is present
+  # @param key [Symbol, String] Parameter key
+  # @return [Boolean]
+  def param_present?(key)
+    params[key].present?
+  end
+  
+  # Get filters applied from params
+  # @param filter_keys [Array<Symbol>] Keys to check for filters
+  # @return [Hash, nil] Hash of applied filters or nil if none
+  def filters_applied(filter_keys = [:category_id, :level, :status, :sort_by, :limit])
+    filters = {}
+    
+    filter_keys.each do |key|
+      filters[key] = params[key] if params[key].present?
+    end
+    
+    filters.empty? ? nil : filters
+  end
+end

data/app/serializers/application_serializer.rb

@@ -0,0 +1,88 @@
+# ApplicationSerializer - Base class for all serializers
+# 
+# This follows Rails convention (like ApplicationRecord, ApplicationController).
+# All your model serializers should inherit from this class.
+#
+# @example Creating a model serializer
+#   class ProductSerializer < ApplicationSerializer
+#     def serializable_hash
+#       case context[:view]
+#       when :summary
+#         summary_hash
+#       when :minimal
+#         minimal_hash
+#       else
+#         full_hash
+#       end
+#     end
+#     
+#     private
+#     
+#     def full_hash
+#       {
+#         id: resource.id,
+#         name: resource.name,
+#         description: resource.description,
+#         price: resource.price,
+#         created_at: resource.created_at
+#       }
+#     end
+#     
+#     def summary_hash
+#       {
+#         id: resource.id,
+#         name: resource.name,
+#         price: resource.price
+#       }
+#     end
+#     
+#     def minimal_hash
+#       {
+#         id: resource.id,
+#         name: resource.name
+#       }
+#     end
+#   end
+class ApplicationSerializer
+  attr_reader :resource, :context
+
+  # Initialize serializer with resource and optional context
+  # @param resource [Object] The object to serialize
+  # @param context [Hash] Additional context (e.g., current_user, view type)
+  def initialize(resource, context = {})
+    @resource = resource
+    @context = context
+  end
+
+  # Override this method in your serializers
+  # @return [Hash] Serialized representation of the resource
+  def serializable_hash
+    raise NotImplementedError, "#{self.class.name} must implement #serializable_hash"
+  end
+
+  # Access to current_user from context
+  # @return [User, nil]
+  def current_user
+    @context[:current_user]
+  end
+
+  # Access to view type from context
+  # @return [Symbol, nil] e.g., :summary, :minimal, :full
+  def view
+    @context[:view]
+  end
+
+  # Helper to serialize associations
+  # @param association [Object, Array] Association to serialize
+  # @param serializer_class [Class] Serializer class to use
+  # @return [Hash, Array<Hash>]
+  def serialize_association(association, serializer_class)
+    return nil if association.nil?
+    
+    if association.respond_to?(:map)
+      association.map { |item| serializer_class.new(item, context).serializable_hash }
+    else
+      serializer_class.new(association, context).serializable_hash
+    end
+  end
+end

data/lib/jsonapi_responses/respondable.rb

@@ -212,7 +212,17 @@ module JsonapiResponses
     end
 
     def respond_for_index(record, serializer_class, context)
-      render json: serialize_collection(record, serializer_class, context)
+      response = { data: serialize_collection(record, serializer_class, context) }
+      
+      # Auto-detect pagination and add meta if available
+      if paginated?(record)
+        response[:meta] = pagination_meta(record, context)
+      elsif context[:meta]
+        # Allow manual meta from context
+        response[:meta] = context[:meta]
+      end
+      
+      render json: response
     end
 
     def respond_for_show(record, serializer_class, context)
@@ -259,5 +269,25 @@ module JsonapiResponses
         ]
       }, status: :bad_request
     end
+
+    # Check if record is paginated (Kaminari or WillPaginate support)
+    def paginated?(record)
+      record.respond_to?(:current_page) && 
+      record.respond_to?(:total_pages) &&
+      record.respond_to?(:total_count)
+    end
+
+    # Extract pagination metadata from paginated record
+    def pagination_meta(record, context = {})
+      base_meta = {
+        current_page: record.current_page,
+        total_pages: record.total_pages,
+        total_count: record.total_count,
+        per_page: record.try(:limit_value) || record.try(:per_page) || context[:per_page]
+      }.compact
+      
+      # Merge with any additional meta from context
+      context[:meta] ? base_meta.merge(context[:meta]) : base_meta
+    end
   end
 end

data/lib/jsonapi_responses/responder.rb

@@ -0,0 +1,149 @@
+module JsonapiResponses
+  # Base class for custom responders
+  # Responders encapsulate response logic for custom actions,
+  # keeping controllers clean and promoting reusability.
+  #
+  # @example Basic usage
+  #   class FeaturedResponder < JsonapiResponses::Responder
+  #     def render
+  #       controller.render json: {
+  #         data: serialize_collection(record),
+  #         meta: {
+  #           type: 'featured',
+  #           count: record.count
+  #         }
+  #       }
+  #     end
+  #   end
+  #
+  # @example Using in controller
+  #   def featured
+  #     @academies = Academy.featured
+  #     render_with(@academies, responder: FeaturedResponder)
+  #   end
+  class Responder
+    attr_reader :controller, :record, :serializer_class, :context
+
+    # @param controller [ActionController::Base] The controller instance
+    # @param record [Object, Array, ActiveRecord::Relation] The record(s) to serialize
+    # @param serializer_class [Class] The serializer class to use
+    # @param context [Hash] Additional context for serialization
+    def initialize(controller, record, serializer_class, context = {})
+      @controller = controller
+      @record = record
+      @serializer_class = serializer_class
+      @context = context
+    end
+
+    # Render the response. Must be implemented by subclasses.
+    # @raise [NotImplementedError] if not implemented in subclass
+    def render
+      raise NotImplementedError, "#{self.class.name} must implement #render method"
+    end
+
+    protected
+
+    # Serialize a collection of records
+    # @param records [Array, ActiveRecord::Relation] Records to serialize
+    # @param custom_serializer [Class, nil] Optional custom serializer
+    # @param custom_context [Hash, nil] Optional custom context
+    # @return [Array<Hash>] Serialized collection
+    def serialize_collection(records = nil, custom_serializer = nil, custom_context = nil)
+      records ||= record
+      serializer = custom_serializer || serializer_class
+      ctx = custom_context || context
+      
+      controller.send(:serialize_collection, records, serializer, ctx)
+    end
+
+    # Serialize a single record
+    # @param item [Object] Record to serialize
+    # @param custom_serializer [Class, nil] Optional custom serializer
+    # @param custom_context [Hash, nil] Optional custom context
+    # @return [Hash] Serialized record
+    def serialize_item(item = nil, custom_serializer = nil, custom_context = nil)
+      item ||= record
+      serializer = custom_serializer || serializer_class
+      ctx = custom_context || context
+      
+      controller.send(:serialize_item, item, serializer, ctx)
+    end
+
+    # Access to params from the controller
+    # @return [ActionController::Parameters]
+    def params
+      controller.params
+    end
+
+    # Access to current_user from the controller (if available)
+    # @return [Object, nil]
+    def current_user
+      controller.respond_to?(:current_user, true) ? controller.send(:current_user) : nil
+    end
+
+    # Helper to render JSON directly through the controller
+    # @param data [Hash] Data to render
+    # @param options [Hash] Additional render options (status, etc.)
+    def render_json(data, options = {})
+      controller.render({ json: data }.merge(options))
+    end
+
+    # Helper to check if record is a collection
+    # @return [Boolean]
+    def collection?
+      record.is_a?(Array) || 
+      record.is_a?(ActiveRecord::Relation) ||
+      (record.respond_to?(:to_a) && !record.is_a?(Hash))
+    end
+
+    # Helper to check if record is a single item
+    # @return [Boolean]
+    def single_item?
+      !collection?
+    end
+
+    # Check if record is paginated (Kaminari or WillPaginate support)
+    # @return [Boolean]
+    def paginated?
+      record.respond_to?(:current_page) && 
+      record.respond_to?(:total_pages) &&
+      record.respond_to?(:total_count)
+    end
+
+    # Extract pagination metadata from paginated record
+    # @return [Hash, nil] Pagination metadata or nil if not paginated
+    def pagination_meta
+      return nil unless paginated?
+      
+      {
+        current_page: record.current_page,
+        total_pages: record.total_pages,
+        total_count: record.total_count,
+        per_page: record.try(:limit_value) || record.try(:per_page)
+      }.compact
+    end
+
+    # Render collection with automatic pagination support
+    # @param records [Array, ActiveRecord::Relation] Records to render
+    # @param additional_meta [Hash] Additional metadata to include
+    def render_collection_with_meta(records = nil, additional_meta = {})
+      records ||= record
+      response = { data: serialize_collection(records) }
+      
+      # Auto-detect pagination
+      if records.respond_to?(:current_page)
+        meta = {
+          current_page: records.current_page,
+          total_pages: records.total_pages,
+          total_count: records.total_count,
+          per_page: records.try(:limit_value) || records.try(:per_page)
+        }.compact
+        response[:meta] = meta.merge(additional_meta)
+      elsif additional_meta.any?
+        response[:meta] = additional_meta
+      end
+      
+      render_json(response)
+    end
+  end
+end

data/lib/jsonapi_responses/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsonapiResponses
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_responses
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Oscar Ortega
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-10-08 00:00:00.000000000 Z
+date: 2025-11-22 00:00:00.000000000 Z
 dependencies: []
 description: JsonapiResponses simplifies API response handling by allowing multiple
   response formats from a single endpoint, improving performance and reducing endpoint
@@ -28,11 +28,14 @@ files:
 - README.md
 - Rakefile
 - app/models/item.rb
+- app/responders/application_responder.rb
+- app/serializers/application_serializer.rb
 - app/serializers/item_serializer.rb
 - config/database.yml
 - lib/jsonapi_responses.rb
 - lib/jsonapi_responses/engine.rb
 - lib/jsonapi_responses/respondable.rb
+- lib/jsonapi_responses/responder.rb
 - lib/jsonapi_responses/serializable.rb
 - lib/jsonapi_responses/user_context_provider.rb
 - lib/jsonapi_responses/version.rb