jsonapi_responses 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '066548a9ebf27a83035e88ae033d84a8aee310cb6ee13fb4e789498ebdfa5d72'
-  data.tar.gz: 8714c314df3e5125f56cfd79119dc5acbdf1aaa66583dce4ed6e74faa13ca25c
+  metadata.gz: 11bbed404d793a44a7b6919b8983aec8906607a0002aa7c4836c302560fbde42
+  data.tar.gz: 1fd4af80b2c031485c183f731831da1a701a09bb56f9ef9f91cff828b563214a
 SHA512:
-  metadata.gz: d2c2603d5d6f1cf28211af7742f22954562b84283d2818f1bfab517e305b5aa86bf2a7f5214e2b9c8e1d558371f8d440b138a58086faa4d814d4cfd22f5e476a
-  data.tar.gz: db9adb8eb6635f91fd5d18595285d7d42dc1f4aac13be52d4471f572a5404defe6abde66d816b51f68357ff78587241026a2509d5ae86a864848d00a5ead5869
+  metadata.gz: 9374e197eeedc859252d9a00a430db4f991a29961571cd5371e58337cc1ce49796b3c97b4dacd336ee259594a1e3f68e583234537d7c74c37fa76cc24c2c0651
+  data.tar.gz: 95d89c45870cbbea7a021a1479205cd30684386c0881313adde2f425635befa04eb86d86ab030a7f5530997312619f1247f971777891cc0c1e4bf7c467a1b7b2

data/.ruby-version

@@ -1 +1 @@
-3.3.6
+ruby-4.0.1

data/CHANGELOG.md

@@ -1,6 +1,45 @@
 ## [Unreleased]
 
-## [1.1.0] - 2025-11-21
+## [1.2.0] - 2026-02-20
+
+- **`serialize_for(action)` in Responder**: Serializes the record using a named method on the serializer if it exists, falling back to `serializable_hash` otherwise. Mirrors the Pundit convention — define `def confirm` in your serializer to get a custom shape for that action without duplicating logic in the responder.
+- **Graceful serializer resolution**: `render_with` no longer raises `NameError` if the inferred serializer class does not exist. When no `serializer:` option is passed and the conventional name (e.g. `ConfirmationSerializer`) cannot be found, `serializer_class` resolves to `nil` and the responder can use `serialize_for` or `render_json` directly.
+
+### Changed
+
+- **Serializer responsibility boundary clarified**: The serializer owns the *shape* of the object (including per-action shapes via named methods); the responder owns the *envelope* of the response (`data:`, `message:`, `meta:`, etc.).
+
+### Example
+
+```ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < ApplicationSerializer
+  def serializable_hash
+    case view
+    when :minimal then minimal_hash
+    else summary_hash
+    end
+  end
+
+  # Action-scoped shape — called by serialize_for(:confirm)
+  def confirm = auth_hash
+
+  private
+
+  def auth_hash
+    { id: resource.id, email: resource.email, confirmed: resource.confirmed? }
+  end
+end
+
+# app/responders/confirmation_responder.rb
+class ConfirmationResponder < ApplicationResponder
+  def confirm
+    render_json({ message: context[:message], user: serialize_for(:confirm) })
+  end
+end
+```
+
+ - 2025-11-21
 
 ### Added
 

data/README.md

@@ -301,6 +301,42 @@ Available helpers:
 - `pagination_meta(record, context)` - Extract pagination metadata hash
 - `render_collection_with_meta(record, serializer_class, context)` - Render with automatic pagination
 
+## Security & Authorization
+
+The `view` parameter is a client-side suggestion and should never be trusted blindly. In a production environment, you must validate whether the `current_user` has permission to see the requested level of detail.
+
+### Secure by Default Pattern
+
+Use your authorization logic (like Pundit) inside the serializer to enforce security:
+
+```ruby
+class DigitalProductSerializer < ApplicationSerializer
+  def serializable_hash
+    # Validate the view against permissions
+    authorized_view = authorize_view(context[:view] || :summary)
+
+    case authorized_view
+    when :full then full_hash
+    when :summary then summary_hash
+    else minimal_hash
+    end
+  end
+
+  private
+
+  def authorize_view(requested_view)
+    return requested_view unless requested_view == :full
+    
+    # Check permission for the 'full' view
+    if Pundit.policy!(context[:current_user], resource).show_full?
+      :full
+    else
+      :summary # Fallback to a safe view
+    end
+  end
+end
+```
+
 ## 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.
@@ -378,14 +414,48 @@ end
 
 ## Custom Responders - Pundit-Style Pattern (Recommended)
 
-For complex custom actions with specialized response logic, use **one Responder class per controller** (similar to Pundit's policy pattern). This keeps your codebase organized and maintainable.
+For complex actions or non-standard logic (like `bulk_upload`, `export_csv`, or `dashboard_stats`), Responders provide a clean way to encapsulate response logic outside of your controllers.
+
+### Handling Non-Standard Actions
 
-### Why Use Responders?
+If you have an action that doesn't fit the standard CRUD pattern, you can use the `action:` parameter to route the response to a specific method in your responder.
 
-- **Separation of Concerns**: Keep response logic out of controllers
-- **One Class Per Controller**: Similar to Pundit policies - easy to find and maintain
-- **Testability**: Test response logic independently
-- **Scalability**: Add new actions without creating new files
+**1. Define the action in your Responder:**
+
+```ruby
+# app/responders/product_responder.rb
+class ProductResponder < ApplicationResponder
+  # Custom action for bulk uploads
+  def bulk_upload
+    render_json({
+      data: serialize_collection(record),
+      meta: {
+        processed_at: Time.current,
+        total_records: record.count,
+        status: 'completed'
+      }
+    })
+  end
+end
+```
+
+**2. Call it from your Controller:**
+
+```ruby
+class Api::V1::ProductsController < ApplicationController
+  def bulk_upload
+    @products = Product.where(id: params[:ids])
+    # The 'action' parameter tells the responder which method to execute
+    render_with(@products, responder: ProductResponder, action: :bulk_upload)
+  end
+end
+```
+
+### Why Use Responders for "Rare" Actions?
+
+- **Clean Controllers**: Your controller only handles business logic and fetching data.
+- **Specific Metadata**: Non-standard actions often require unique `meta` tags that would clutter a controller.
+- **Organization**: Even if you have "weird" actions, they remain organized within the Responder assigned to that controller.
 
 ### The Pundit-Style Approach
 
@@ -546,6 +616,9 @@ class MyCustomResponder < JsonapiResponses::Responder
     serialize_collection(record)  # For collections
     serialize_item(record)         # For single items
 
+    # Serialize using a named method on the serializer (falls back to serializable_hash)
+    serialize_for(:my_action)      # Calls serializer.my_action if defined
+
     # Check record type
     collection?    # true if record is a collection
     single_item?   # true if record is a single item
@@ -556,6 +629,84 @@ class MyCustomResponder < JsonapiResponses::Responder
 end
 ```
 
+## Action-Scoped Serialization with `serialize_for`
+
+For actions with a custom response envelope (like an email confirmation that returns `{ message:, user: }` instead of the standard `{ data: }`), you can define a named method on the serializer to describe the exact shape of the object for that action.
+
+This mirrors the Pundit convention: just as `PostPolicy#publish?` handles the `publish` action, `UserSerializer#confirm` handles the `confirm` action.
+
+**Rule:** the serializer owns the *shape* of the object; the responder owns the *envelope*.
+
+### How it works
+
+`serialize_for(:action)` instantiates the serializer and calls `.action` on it if defined, otherwise falls back to `serializable_hash`.
+
+### Example
+
+**1. Define the action shape in the serializer** (alongside your existing views):
+
+```ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < ApplicationSerializer
+  def serializable_hash
+    case view
+    when :minimal then minimal_hash
+    when :profile then profile_hash
+    else summary_hash
+    end
+  end
+
+  # Custom shape for the confirm action — reuses an existing private method
+  def confirm = auth_hash
+
+  private
+
+  def summary_hash = { id: resource.id, email: resource.email }
+  def auth_hash    = { id: resource.id, email: resource.email, confirmed: resource.confirmed? }
+end
+```
+
+**2. Use `serialize_for` in the responder** — no shape logic leaks in:
+
+```ruby
+# app/responders/confirmation_responder.rb
+class ConfirmationResponder < ApplicationResponder
+  def confirm
+    render_json({
+      message: context[:message],
+      user: serialize_for(:confirm)   # → UserSerializer#confirm
+    })
+  end
+end
+```
+
+**3. Controller stays minimal:**
+
+```ruby
+class Api::V1::ConfirmationsController < ApplicationController
+  def confirm
+    # ... validation logic ...
+    render_with(
+      user,
+      responder: ConfirmationResponder,
+      action: :confirm,
+      serializer: UserSerializer,
+      context: { message: I18n.t("auth.confirmation.success") }
+    )
+  end
+end
+```
+
+### Fallback behaviour
+
+If the serializer does not define the named method, `serialize_for` silently falls back to `serializable_hash`, so existing serializers require no changes.
+
+```ruby
+serialize_for(:confirm)  # → UserSerializer#confirm   (if defined)
+serialize_for(:confirm)  # → UserSerializer#serializable_hash  (fallback)
+```
+
+
 ### Complex Example: Categorized Response
 
 ```ruby

data/lib/jsonapi_responses/respondable.rb

@@ -167,7 +167,11 @@ module JsonapiResponses
       context = (options[:context] || {}).merge(serialization_user)
       # Only use params[:view] if view is not already provided in context
       context[:view] ||= params[:view]&.to_sym
-      serializer_class = options[:serializer] || "#{controller_name.singularize.camelize}Serializer".constantize
+      serializer_class = options[:serializer] || begin
+        "#{controller_name.singularize.camelize}Serializer".constantize
+      rescue NameError
+        nil
+      end
       
       # If a custom responder is provided, use it
       if options[:responder]

data/lib/jsonapi_responses/responder.rb

@@ -69,6 +69,29 @@ module JsonapiResponses
       controller.send(:serialize_item, item, serializer, ctx)
     end
 
+    # Serialize the record using a named method on the serializer if it exists,
+    # otherwise falls back to serializable_hash.
+    # Mirrors the Pundit convention: action name on the serializer = custom shape.
+    #
+    # @example In a serializer
+    #   def confirm = auth_hash   # custom shape for the confirm action
+    #
+    # @example In a responder
+    #   def confirm
+    #     render_json({ message: context[:message], user: serialize_for(:confirm) })
+    #   end
+    #
+    # @param action [Symbol] The action name to look up on the serializer
+    # @param item [Object, nil] Record to serialize (defaults to record)
+    # @param custom_serializer [Class, nil] Override serializer class
+    # @param custom_context [Hash, nil] Override context
+    # @return [Hash] Serialized representation
+    def serialize_for(action, item = nil, custom_serializer = nil, custom_context = nil)
+      item ||= record
+      serializer = (custom_serializer || serializer_class).new(item, custom_context || context)
+      serializer.respond_to?(action) ? serializer.public_send(action) : serializer.serializable_hash
+    end
+
     # Access to params from the controller
     # @return [ActionController::Parameters]
     def params
@@ -91,8 +114,8 @@ module JsonapiResponses
     # Helper to check if record is a collection
     # @return [Boolean]
     def collection?
-      record.is_a?(Array) || 
-      record.is_a?(ActiveRecord::Relation) ||
+      record.is_a?(Array) ||
+      (defined?(ActiveRecord::Relation) && record.is_a?(ActiveRecord::Relation)) ||
       (record.respond_to?(:to_a) && !record.is_a?(Hash))
     end
 

data/lib/jsonapi_responses/serializable.rb

@@ -10,7 +10,7 @@ module JsonapiResponses
     end
 
     def serialize_item(item, serializer_class, context = {})
-      serializer_class.new(item, context).serializable_hash
+      serializer_class.new(item, context || {}).serializable_hash
     end
   end
 end

data/lib/jsonapi_responses/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi_responses
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Oscar Ortega
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-11-22 00:00:00.000000000 Z
+date: 1980-01-02 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
@@ -49,7 +48,6 @@ metadata:
   documentation_uri: https://github.com/oortega14/jsonapi_responses#readme
   changelog_uri: https://github.com/oortega14/jsonapi_responses/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -64,8 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A simple way to handle multiple JSON response formats in Rails APIs
 test_files: []