active_call 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4673cf511194223bf9481aa7ed85507c9162556b20469f28c9421cc59f4230a9
-  data.tar.gz: 20fed6531fd0ac7bc7c6e6f8ffb03d336c82e6b91131354c3c5da6e202ea56b0
+  metadata.gz: d67030b5b5cf7b405b842c1295c33912ebaa2b6ad1aeaefa0807e1a0f4fef105
+  data.tar.gz: 6b19ccf7e464102efe1e70ab0501ea6bb3aa8a781880f1492cca1bfeee9de576
 SHA512:
-  metadata.gz: 0064c55032419b699535d0f19cfbf90d730089f57da8a7ac360bdb96fbb7f40dc6d2a19859baec6074e180aef6ef290a45bb818ba872a5418f2ad8c0432786cf
-  data.tar.gz: bea908f7aeb097617edaf7694a5fffd21e8ef6f3a90f8fdcebd8e4efd23cf90fba289df598914c35540b16400b7ae46dd6ce4c4bd5df29e1b42feb1ad6dabfa2
+  metadata.gz: 5b0aea3b486558cd5d81ead4cbc1e75c1ae97f1edef31b3d9ed796b04cdb78e24e6aeda57227ade6c927f7a90599dfe16c06dc8065b98dcbb340db8a27f279e4
+  data.tar.gz: 46f8fa215650ff0373ada16c79a7bd3f2f5a73ff8aaea30081a6e59ade1a869ac3aff735c132d87bc3774708ef13c2dc7829d802774b238f6acd74a061589063

data/.rubocop.yml

@@ -15,6 +15,9 @@ AllCops:
     - 'vendor/**/*'
     - 'gem/**/*'
 
+Layout/LineEndStringConcatenationIndentation:
+  EnforcedStyle: indented
+
 Lint/MissingSuper:
   AllowedParentClasses:
     - ActiveCall::Base
@@ -23,6 +26,11 @@ Metrics/BlockLength:
   Exclude:
     - spec/*/**.rb
 
+Metrics/MethodLength:
+  AllowedMethods:
+    - call
+    - call!
+
 RSpec/ExampleLength:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.2.1] - 2025-03-25
+
+- Gemspec `changelog_uri` fixed.
+
+## [0.2.0] - 2025-03-20
+
+- Added method `.call!` with a bang, which will raise an `ActiveCall::ValidationError` exception when validation fails and an `ActiveCall::RequestError` exception when errors were added to the service object in the `validate on: :response` block.
+- Use new method `success?` instead of `valid?`.
+- Method `valid?` will return `true` if the service object passed validation and was able to make the `call` method.
+- Use `validate, on: :response` to validate the response object.
+- Raise `NotImplementedError` when `call` is not defined in subclasses.
+- Use `self.abstract_class = true` to treat the class as a base class that does not define a `call` method.
+- Adding a `@bang` instance variable on the service objects to determine if `call` or `call!` was invoked.
+- Don't set `@response` if the object is an `Enumerable`. The response will be set in `each` and not `call`.
+
 ## [0.1.0] - 2025-03-08
 
 - Initial release

data/README.md

@@ -1,49 +1,69 @@
 # Active Call
 
+[![Gem Version](https://badge.fury.io/rb/active_call.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/active_call)
+
 Active Call provides a standardized way to create service objects.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add active_call
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install active_call
 ```
 
 ## Usage
 
 Your child classes should inherit from `ActiveCall::Base`.
 
-Now you can start adding your own service object classes in your gem's `lib` folder.
+You can add your own service object classes in your gem's `lib` folder or your project's `app/services` folder.
 
 Each service object must define only one public method named `call`.
 
-A `response` attribute is set with the result of the `call` method.
+### Logic Flow
+
+1. **Before** invoking `call`.
+
+  - Validate the request with `validates`.
+
+  - Use the `before_call` hook to set up anything **after validation** passes.
+
+2. **During** `call` invocation.
+
+  - A `response` attribute gets set with the result of the `call` method.
 
-An `errors` object will be set if you specified any validations that failed before the `call` method could be invoked.
+3. **After** invoking `call`.
 
-There is also a `before_call` hook to set up anything before invoking the `call` method. This only happens after all validations have passed.
+  - Validate the response with `validate, on: :response`.
+
+  - Use the `after_call` hook to set up anything **after response validation** passes.
+
+### Example Service Object
 
 Define a service object with optional validations and callbacks.
 
 ```ruby
 require 'active_call'
 
-class YourGemName::SomeResource::GetService < ActiveCall::Base
+class YourGem::SomeResource::CreateService < ActiveCall::Base
   attr_reader :message
 
   validates :message, presence: true
 
+  validate on: :response do
+    errors.add(:message, :invalid, message: 'cannot be baz') if response[:foo] == 'baz'
+  end
+
   before_call :strip_message
 
+  after_call :log_response
+
   def initialize(message: nil)
     @message = message
   end
@@ -57,48 +77,108 @@ class YourGemName::SomeResource::GetService < ActiveCall::Base
   def strip_message
     @message.strip!
   end
+
+  def log_response
+    puts "Successfully called #{response}"
+  end
 end
 ```
 
-You will get a **response** object.
+### Using `call`
+
+You will get an **errors** object when validation fails.
 
 ```ruby
-service = YourGemName::SomeResource::GetService.call(message: ' bar ')
-service.valid? # => true
-service.response # => { foo: 'bar' }
+service = YourGem::SomeResource::CreateService.call(message: '')
+service.success? # => false
+service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=blank, options={}>]>
+service.errors.full_messages # => ["Message can't be blank"]
+service.response # => nil
 ```
 
-And an **errors** object when validation failed.
+A **response** object on a successful `call` invocation.
 
 ```ruby
-service = YourGemName::SomeResource::GetService.call(message: '')
-service.valid? # => false
-service.errors.full_messages # => ["Message can't be blank"]
-service.response # => nil
+service = YourGem::SomeResource::CreateService.call(message: ' bar ')
+service.success? # => true
+service.response # => {:foo=>"bar"}
+```
+
+And an **errors** object if you added errors during the `validate, on: :response` validation.
+
+```ruby
+service = YourGem::SomeResource::CreateService.call(message: 'baz')
+service.success? # => false
+service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=invalid, options={:message=>"cannot be baz"}>]>
+service.errors.full_messages # => ["Message cannot be baz"]
+service.response # => {:foo=>"baz"}
+```
+
+### Using `call!`
+
+An `ActiveCall::ValidationError` **exception** gets raised when validation fails.
+
+```ruby
+begin
+  service = YourGem::SomeResource::CreateService.call!(message: '')
+rescue ActiveCall::ValidationError => exception
+  exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=blank, options={}>]>
+  exception.errors.full_messages # => ["Message can't be blank"]
+end
+```
+
+A **response** object on a successful `call` invocation.
+
+```ruby
+service = YourGem::SomeResource::CreateService.call!(message: ' bar ')
+service.success? # => true
+service.response # => {:foo=>"bar"}
+```
+
+And an `ActiveCall::RequestError` **exception** gets raised if you added errors during the `validate, on: :response` validation.
+
+```ruby
+begin
+  service = YourGem::SomeResource::CreateService.call!(message: 'baz')
+rescue ActiveCall::RequestError => exception
+  exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=invalid, options={:message=>"cannot be baz"}>]>
+  exception.errors.full_messages # => ["Message cannot be baz"]
+  exception.response # => {:foo=>"baz"}
+end
 ```
 
+## Configuration
+
 If you have secrets, use a **configuration** block.
 
 ```ruby
-require 'net/http'
+class YourGem::BaseService < ActiveCall::Base
+  self.abstract_class = true
 
-class YourGemName::BaseService < ActiveCall::Base
   config_accessor :api_key, default: ENV['API_KEY'], instance_writer: false
-
-  def call
-    Net::HTTP.get_response(URI("http://example.com/api?#{URI.encode_www_form(api_key: api_key)}"))
-  end
 end
 ```
 
-Then in your application code you can overrite the configuration defaults.
+Then in your application code you can override the configuration defaults.
 
 ```ruby
-YourGemName::BaseService.configure do |config|
+YourGem::BaseService.configure do |config|
   config.api_key = Rails.application.credentials.api_key || ENV['API_KEY']
 end
 ```
 
+And implement a service object like so.
+
+```ruby
+require 'net/http'
+
+class YourGem::SomeResource::CreateService < YourGem::BaseService
+  def call
+    Net::HTTP.get_response(URI("http://example.com/api?#{URI.encode_www_form(api_key: api_key)}"))
+  end
+end
+```
+
 ## Gem Creation
 
 To create your own gem for a service.
@@ -121,6 +201,11 @@ spec.add_dependency 'active_call'
 
 Now start adding your service objects in the `lib` directory and make sure they inherit from `ActiveCall::Base`.
 
+## Gems Using Active Call
+
+- [nCino KYC DocFox](https://github.com/kobusjoubert/doc_fox)
+- [Zoho Sign](https://github.com/kobusjoubert/zoho_sign)
+
 ## 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.

data/lib/active_call/base.rb

@@ -10,15 +10,141 @@ class ActiveCall::Base
   define_model_callbacks :call
 
   class << self
+    # Set your class to `self.abstract_class = true` if the class is used as a base class and not as a service object.
+    # Abstract classes are not meant to be instantiated directly, but rather inherited from.
+    # The `call` method doesn't need to be implemented in abstract classes.
+    #
+    # ==== Examples
+    #
+    #   class YourGem::BaseService < ActiveCall::Base
+    #     self.abstract_class = true
+    #   end
+    #
+    #   class YourGem::SomeResource::CreateService < YourGem::BaseService
+    #     def call
+    #       # Implementation specific to this service.
+    #     end
+    #   end
+    #
+    attr_accessor :abstract_class
+
+    def abstract_class?
+      @abstract_class == true
+    end
+
+    # TODO: Refactor `call` and `call!`. The only differences are the two lines raising exceptions.
+
+    # Using `call`
+    #
+    # ==== Examples
+    #
+    # You will get an `errors` object when validation fails.
+    #
+    #   service = YourGem::SomeResource::CreateService.call(message: '')
+    #   service.success? # => false
+    #   service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=blank, options={}>]>
+    #   service.errors.full_messages # => ["Message can't be blank"]
+    #   service.response # => nil
+    #
+    # A `response` object on a successful `call` invocation.
+    #
+    #   service = YourGem::SomeResource::CreateService.call(message: ' bar ')
+    #   service.success? # => true
+    #   service.response # => {:foo=>"bar"}
+    #
+    # And an `errors` object if you added errors during the `validate, on: :response` validation.
+    #
+    #   service = YourGem::SomeResource::CreateService.call(message: 'baz')
+    #   service.success? # => false
+    #   service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=invalid, options={:message=>"cannot be baz"}>]>
+    #   service.errors.full_messages # => ["Message cannot be baz"]
+    #   service.response # => {:foo=>"baz"}
+    #
     def call(...)
       service_object = new(...)
-      return service_object if service_object.invalid?
+      service_object.instance_variable_set(:@bang, false)
+      return service_object if service_object.invalid?(except_on: :response)
 
       service_object.run_callbacks(:call) do
+        next if service_object.is_a?(Enumerable)
+
         service_object.instance_variable_set(:@response, service_object.call)
+        service_object.validate(:response)
+
+        return service_object unless service_object.success?
       end
 
       service_object
     end
+
+    # Using `call!`
+    #
+    # ==== Examples
+    #
+    # An `ActiveCall::ValidationError` exception gets raised when validation fails.
+    #
+    #   begin
+    #     service = YourGem::SomeResource::CreateService.call!(message: '')
+    #   rescue ActiveCall::ValidationError => exception
+    #     exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=blank, options={}>]>
+    #     exception.errors.full_messages # => ["Message can't be blank"]
+    #   end
+    #
+    # A `response` object on a successful `call` invocation.
+    #
+    #   service = YourGem::SomeResource::CreateService.call!(message: ' bar ')
+    #   service.success? # => true
+    #   service.response # => {:foo=>"bar"}
+    #
+    # And an `ActiveCall::RequestError` exception gets raised if you added errors during the `validate, on: :response`
+    # validation.
+    #
+    #   begin
+    #     service = YourGem::SomeResource::CreateService.call!(message: 'baz')
+    #   rescue ActiveCall::RequestError => exception
+    #     exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=invalid, options={:message=>"cannot be baz"}>]>
+    #     exception.errors.full_messages # => ["Message cannot be baz"]
+    #     exception.response # => {:foo=>"baz"}
+    #   end
+    #
+    def call!(...)
+      service_object = new(...)
+      service_object.instance_variable_set(:@bang, true)
+      raise ActiveCall::ValidationError, service_object.errors if service_object.invalid?(except_on: :response)
+
+      service_object.run_callbacks(:call) do
+        next if service_object.is_a?(Enumerable)
+
+        service_object.instance_variable_set(:@response, service_object.call)
+        service_object.validate(:response)
+
+        unless service_object.success?
+          raise ActiveCall::RequestError.new(service_object.response, service_object.errors)
+        end
+      end
+
+      service_object
+    end
+  end
+
+  def success?
+    errors.empty?
+  end
+
+  def valid?(context = nil)
+    return true if response
+
+    super
+  end
+
+  def bang?
+    !!@bang
+  end
+
+  def call
+    return if self.class.abstract_class?
+
+    raise NotImplementedError, 'Subclasses must implement a call method. If this is an abstract base class, set ' \
+      '`self.abstract_class = true`.'
   end
 end

data/lib/active_call/concerns/request_errorable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveCall::RequestErrorable
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :response, :errors
+  end
+
+  def initialize(response = nil, errors = ActiveModel::Errors.new(self), message = nil)
+    @response = response
+    @errors   = errors
+    message   ||= errors.full_messages.to_sentence.presence || 'Request failed'
+
+    super(message)
+  end
+end

data/lib/active_call/concerns/validation_errorable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveCall::ValidationErrorable
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :errors
+  end
+
+  def initialize(errors = ActiveModel::Errors.new(self), message = nil)
+    @errors = errors
+    message ||= errors.full_messages.to_sentence.presence || 'Validation failed'
+
+    super(message)
+  end
+end

data/lib/active_call/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveCall
+  class Error < StandardError; end
+
+  class ValidationError < Error
+    include ActiveCall::ValidationErrorable
+  end
+
+  class RequestError < Error
+    include ActiveCall::RequestErrorable
+  end
+end

data/lib/active_call/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveCall
-  VERSION = '0.1.0'
+  VERSION = '0.2.1'
 end

data/lib/active_call.rb

@@ -3,11 +3,12 @@
 require 'active_model'
 require 'zeitwerk'
 
-require_relative 'active_call/version'
-
 loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/active_call/error.rb")
+loader.collapse("#{__dir__}/active_call/concerns")
 loader.setup
 
-module ActiveCall
-  class Error < StandardError; end
-end
+require_relative 'active_call/error'
+require_relative 'active_call/version'
+
+module ActiveCall; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_call
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kobus Joubert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -53,6 +53,9 @@ files:
 - Rakefile
 - lib/active_call.rb
 - lib/active_call/base.rb
+- lib/active_call/concerns/request_errorable.rb
+- lib/active_call/concerns/validation_errorable.rb
+- lib/active_call/error.rb
 - lib/active_call/version.rb
 - sig/active_call.rbs
 homepage: https://github.com/kobusjoubert/active_call
@@ -63,7 +66,7 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/kobusjoubert/active_call
   source_code_uri: https://github.com/kobusjoubert/active_call
-  changelog_uri: https://github.com/kobusjoubert/active_call/CHANGELOG.md
+  changelog_uri: https://github.com/kobusjoubert/active_call/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: