api_responser 1.0.0.8 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adee3e3b70fb9ad9b4848000ade2e3e920119d0497ab3d427456016ca1c4e6a4
-  data.tar.gz: 18df245fb706daad93eb2130a6a4472d3686f6c3df167ba80e25f8a0d60e9838
+  metadata.gz: e28a527016ea61d6d5050e1bc049556e1803be3b99d63327e525fc244bc68064
+  data.tar.gz: 1b7399981de0a77cdcc935f828c098d2654a5a9ee72af1acb866563358a30ae2
 SHA512:
-  metadata.gz: 1bf274f302575673ef57194ffca8bf312ebbcaa7411cd3ba12c846275fbc30884b34b33f2de024884f95641d40d4f0426eaf4162726b20f1e5a125c424ab3126
-  data.tar.gz: 302d3c281bc263de67aa3d477b843f4ed7e473526f057cb92488aae5519124a43ff34dc175050276174d03ad8b39b05e83a2f50bacdbbb1c4e028f7347e70d60
+  metadata.gz: 31b9f21ee19f8c88757000df8608f6917ea83e869ac5b26c481d7467ec283f5e7fc0eafdd4291ffe5de35edfeb3784917af29ce150fcf48c081529ea40025f68
+  data.tar.gz: a1ffa33b876ba7047f6c75ac8732f1c13479bef7f1a45480c6499bee89fff85b5ffcd5d36fe2375fc9fdc6e9cb2d44b9709d3eec838c07c61ed517b5ff9eab76

data/config/locales/en.yml

@@ -4,9 +4,9 @@ en:
       access_denied: "Access denied"
       page_not_found: "Page not found"
       record_not_found: "Record not found"
-      record_not_created: "Record not created: %{message}"
-      record_not_updated: "Record not saved: %{message}"
-      record_not_deleted: "Record not deleted: %{message}"
+      record_not_created: "%{message}"
+      record_not_updated: "%{message}"
+      record_not_deleted: "%{message}"  
       bad_request: "Bad request"
       unauthorized: "Unauthorized"
       forbidden: "Forbidden"

data/lib/api_responser.rb

@@ -1,3 +1,5 @@
+require 'erb'
+require 'json'
 require 'rails'
 
 require_relative 'api_responser/railtie' if defined?(Rails)
@@ -19,11 +21,12 @@ module ApiResponser
     end
   end
 
+  # 204 No Content must not carry a body, so a response with records is sent as 200.
   def record_updated(records = nil)
     if records.nil?
       api_success(code: 204)
     else
-      success_render(code: 204, message: i18n_message(__method__, status:"success"), records: records)
+      success_render(code: 200, message: i18n_message(__method__, status:"success"), records: records)
     end
   end
 
@@ -31,7 +34,7 @@ module ApiResponser
     if records.nil?
       api_success(code: 204)
     else
-      success_render(code: 204, message: i18n_message(__method__, status:"success"), records: records)
+      success_render(code: 200, message: i18n_message(__method__, status:"success"), records: records)
     end
   end
 
@@ -114,7 +117,7 @@ module ApiResponser
 
   def success_render(code: 200, message: "", records: nil, records_count: nil)
     @code = code
-    @message = message
+    @message = json_escape(message)
     @records = records
     @records_count = determine_records_count(records, records_count)
     {json: ERB.new(file_read("success")).result(binding), status: code}
@@ -122,11 +125,18 @@ module ApiResponser
 
   def error_render(code: 500, message: "", debug_message: "", report: false)
     @code = code
-    @message = message
+    @message = json_escape(message)
     error_handling(code: code, message: message, debug_message: debug_message) if report == true
     {json: ERB.new(file_read("error")).result(binding), status: code}
   end
 
+  # The JSON templates interpolate @message inside a quoted string literal, so
+  # any quote or backslash in it would otherwise produce unparseable JSON.
+  # to_json gives us the escaped form; the surrounding quotes come from the template.
+  def json_escape(value)
+    value.to_s.to_json[1..-2]
+  end
+
   def file_read(type = "error")
     if defined?(Rails) && Rails.root
       app_view_path = Rails.root.join('app', 'views', 'api_responser', "#{type}.json.erb")
@@ -140,7 +150,7 @@ module ApiResponser
   end
 
   def i18n_message(method_name, status:"error", message: nil)
-    message = message.full_messages.join(', ') if message.is_a?(ActiveModel::Errors)
+    message = message.full_messages.join(', ') if message.respond_to?(:full_messages)
     message = message.join(', ') if message.is_a?(Array)
     I18n.t("api_responser.#{status}.#{method_name}", message: message)
   end
@@ -150,6 +160,17 @@ module ApiResponser
   end
 
   def determine_records_count(records, records_count)
-    records_count || ((records.is_a?(ActiveRecord::Relation) || (records.is_a?(Array))) ? records.count : (records.nil? || records.blank? ? 0 : 1))
+    return records_count if records_count
+    return records.count if collection?(records)
+
+    records.blank? ? 0 : 1
+  end
+
+  # ActiveRecord is not necessarily loaded (e.g. an API app with no database),
+  # so the constant is resolved lazily rather than referenced directly.
+  def collection?(records)
+    return true if records.is_a?(Array)
+
+    defined?(ActiveRecord::Relation) && records.is_a?(ActiveRecord::Relation)
   end
 end

data/readme.md

@@ -13,6 +13,11 @@ A gem to standardize API responses in Rails applications.
 
 All methods return JSON and status.
 
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0 (tested against 7.1 and 8.1)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -43,8 +48,8 @@ end
 
 ## Success Response list
 #### List of Items
-The *records* argument is required and should be an **Array**. The *records_count* argument is an **Integer** and is optional.\
-If *records_count* is not provided, the count will be calculated from the size of the *records* array
+The *records* argument is required and should be an **Array** or an **ActiveRecord::Relation**. The *records_count* argument is an **Integer** and is optional.\
+If *records_count* is not provided, the count will be calculated from the size of *records*. This is useful for pagination, where the rendered page is smaller than the total count
 ```ruby
 def record_index(records, records_count = nil)
 ```
@@ -54,15 +59,23 @@ The *records* argument should be a **Hash**. It should contain only one model
 def record_show(records)
 ```
 #### Item Create / Item Update / Item Delete
-*No arguments* are required
+The *records* argument is optional.
+
+When called *without arguments*, the response has no body and only a status code is returned
+(**201** for create, **204 No Content** for update and delete).
+
+When *records* are passed, the created/updated/deleted record is rendered in the response body
+(**201** for create, **200** for update and delete). Update and delete use **200** rather than **204**
+in this case, because a 204 No Content response is not allowed to carry a body.
+
 ```ruby
-def record_created
+def record_created(records = nil)
 ```
 ```ruby
-def record_updated
+def record_updated(records = nil)
 ```
 ```ruby
-def record_deleted
+def record_deleted(records = nil)
 ```
 
 
@@ -108,6 +121,11 @@ The *message* argument is required, while the *debug_message* argument is option
 The *report* argument is optional and is useful if you would like to handle *debug_message*.\
 The *message* argument is used to output a message in the JSON response, whereas *debug_message* is useful for providing the real reason for the error (if *report* is **true**). 
 
+The *message* argument accepts a **String**, an **Array** of strings, or a model's
+**errors** object (e.g. `item.errors`), which is joined into a single sentence.
+Messages are escaped before being rendered, so text containing quotes, backslashes
+or newlines is safe to pass through.
+
 ```ruby
 def record_not_created(message, debug_message = "", report:false)
 ```
@@ -145,23 +163,29 @@ Templates should be located in **app/views/api_responser/**
 The default templates are:
 #### success.json.erb
 ``` ruby
-"data":{
+{"data": {
   "status": "success",
   "code": <%= @code %>,
   "message": "<%= @message %>",
   "records": <%= @records.to_json %>,
   "records_count": <%= @records_count %>
-}
+}}
 ```
 ####  error.json.erb
 ``` ruby
-"data":{
+{"data": {
   "status": "error",
   "code": <%= @code %>,
   "message": "<%= @message %>"
-}
+}}
 ```
 
+**Note on `@message` in custom templates:** `@message` arrives already escaped for
+JSON, so quotes, backslashes and newlines in a message are safe. It is escaped as
+*string contents only* — the surrounding quotes come from the template, so keep
+`@message` wrapped in `"` as shown above. Values you add yourself should be passed
+through `to_json` (as `@records` is) so the rendered body stays valid JSON.
+
 ## Customizing Error Handling
 The gem provides a default error handler in **ApiResponserHelper**:
 ``` ruby
@@ -172,7 +196,7 @@ module ApiResponserHelper
 end
 ```
 You can customize this method to handle errors in a way that suits your application's requirements. For example, you might want to log errors to a file or send notifications to an external service.
-Helper should be located in **app/helpers/app_responser_helper.rb**
+Helper should be located in **app/helpers/api_responser_helper.rb**
 
 
 ## Localization

metadata

@@ -1,27 +1,26 @@
 --- !ruby/object:Gem::Specification
 name: api_responser
 version: !ruby/object:Gem::Version
-  version: 1.0.0.8
+  version: '1.1'
 platform: ruby
 authors:
 - Nazim Mehdiyev
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
 - !ruby/object:Gem::Dependency
@@ -76,7 +75,6 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/nmehdiyev/ApiResponser
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -84,15 +82,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: A gem to standardize API responses in Rails applications
 test_files: []