authsignal-ruby 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0204e93c2f7fa2b3bf20379b5837243a62960ce0b35c39d69e41f6c98b02125
-  data.tar.gz: 4624f0d600ac6377b4d2ef3945121e7a8dc628852786ca8ecccb2b6c7b589d07
+  metadata.gz: '05993f5ac8d8569efae1a1c17692b90216c135675c922a4ef727124ba4774b5c'
+  data.tar.gz: 7f1816f80f7bf7517fda22b2f5d2cc0ad9895431031b06e0dfdf52dc4065c355
 SHA512:
-  metadata.gz: 6c9592f43a421e9bd5032b3d81aa44a10e30e03553e293667b5ac1ca7b196d4cad3a12e544e41f70392a54649ed584a8ef4a1a9259363e5de4a4104e50f20601
-  data.tar.gz: 1409c27d455564263fb596e1ac920f5867540711ea07a8bd2b85a47a07c0843dded453c3648557e81ac8d6586539bb531d551c2d09c19178b728c6720d005944
+  metadata.gz: eb669c48e8fcb98f9241b0cde59c9aba13b4f1991f83f2e6ca0b127338af6d31c123cac2d3a9dec0cafc19142fb0fe9c5a212f792fb2c5655f22d13757f1dee6
+  data.tar.gz: 1e2622b946b9979010eb0f34a7de0b76eda3197242d441807b1bde5a038fe6cbd6a70a9e94ef54cdad4c23d1298f5d49f3f3a6ec2a11bd47a594775467c48342

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    authsignal-ruby (3.0.0)
+    authsignal-ruby (4.0.0)
       faraday (>= 2)
       faraday-retry (~> 2.2)
 
@@ -14,7 +14,7 @@ GEM
     crack (1.0.0)
       bigdecimal
       rexml
-    diff-lcs (1.5.0)
+    diff-lcs (1.5.1)
     faraday (2.12.0)
       faraday-net_http (>= 2.0, < 3.4)
       json
@@ -29,21 +29,21 @@ GEM
     net-http (0.4.1)
       uri
     public_suffix (6.0.1)
-    rake (13.0.6)
+    rake (13.2.1)
     rexml (3.3.8)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
     uri (0.13.1)
     webmock (3.24.0)
       addressable (>= 2.8.0)
@@ -51,6 +51,7 @@ GEM
       hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
+  arm64-darwin-24
   ruby
 
 DEPENDENCIES
@@ -60,4 +61,4 @@ DEPENDENCIES
   webmock (~> 3.14)
 
 BUNDLED WITH
-   2.3.21
+   2.5.16

data/README.md

@@ -63,6 +63,55 @@ Authsignal's server side signal API has four main api calls `track`, `get_action
 
 For more details on these api calls, refer to our [official Ruby SDK docs](https://docs.authsignal.com/sdks/server/ruby#track).
 
+Example:
+
+```ruby
+Authsignal.track user_id: 'AS_001', action: 'withdraw', idempotency_key: 'a_random_hash'
+
+# returns:
+# {
+#    success?: true,
+#    state: 'ALLOW',
+#    idempotency_key: 'a_random_hash',
+#    ... rest of payload ...
+# }
+```
+
+### Response & Error handling
+
+The Authsignal SDK offers two response formats. By default, its methods return the payload in hash format.
+
+Example:
+
+```ruby
+Authsignal.enroll_verified_authenticator user_id: 'AS_001',
+                                         authenticator: {
+                                           oob_channel: 'INVALID', email: 'joebloke@authsignal.com'
+                                         }
+
+# returns:
+# {
+#    success?: false,
+#    status: 400,
+#    error: 'invalid_request',
+#    error_description: '/body/oobChannel must be equal to one of the allowed values'
+# }
+```
+
+All methods have a bang (!) counterpart that raises an Authsignal::ApiError if the request fails.
+
+Example:
+
+```ruby
+Authsignal.enroll_verified_authenticator! user_id: 'AS_001',
+                                         authenticator: {
+                                           oob_channel: 'INVALID', email: 'joebloke@authsignal.com'
+                                         }
+
+# raise:
+# <Authsignal::ApiError: invalid_request status: 400, error: invalid_request, description: /body/oobChannel must be equal to one o...
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` or `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/authsignal/api_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Authsignal
+  class ApiError < StandardError
+    attr_reader :status, :error, :description
+
+    def initialize(message = "An unexpected API error occurred", status, error, description)
+      @status      = status || 500
+      @error       = error
+      @description = description
+
+      super(message)
+    end
+
+    def to_s
+      "#{super} status: #{status}, error: #{error}, description: #{description}"
+    end
+  end
+end

data/lib/authsignal/client.rb

@@ -63,10 +63,11 @@ module Authsignal
             make_request(:delete, "users/#{url_encode(user_id)}")
         end
 
-        def validate_challenge(user_id: nil, token:)
+        def validate_challenge(user_id: nil, token:, action: nil)
             path = "validate"
+            body = { user_id: user_id, token: token, action: action }
 
-            make_request(:post, path, body: { user_id: user_id, token: token })
+            make_request(:post, path, body: body)
         end
 
         def get_action(user_id, action, idempotency_key)
@@ -83,16 +84,12 @@ module Authsignal
             make_request(:post, "users/#{url_encode(user_id)}/authenticators", body: authenticator)
         end
 
-        def delete_user_authenticator(user_id:, user_authenticator_id:)
+        def delete_authenticator(user_id:, user_authenticator_id:)
             make_request(:delete, "users/#{url_encode(user_id)}/authenticators/#{url_encode(user_authenticator_id)}")
         end
 
         private
 
-        def make_request(method, path, body: nil, headers: nil)
-            @client.public_send(method, path, body, headers)
-        end
-
         def url_encode(s)
             ERB::Util.url_encode(s)
         end
@@ -108,5 +105,12 @@ module Authsignal
         def require_api_key
             Authsignal.configuration.api_secret_key || print_api_key_warning
         end
+
+        def make_request(method, path, body: nil, headers: nil)
+            if body.is_a?(Hash)
+                body = body.reject { |_, v| v.nil? }
+            end
+            @client.public_send(method, path, body, headers)
+        end
     end
 end

data/lib/authsignal/middleware/json_response.rb

@@ -9,6 +9,7 @@ module Authsignal
         # Otherwise, we can safe guard with: env.response_headers['content-type'] =~ /application\/json/
         parsed_body = JSON.parse(env.body)
         if parsed_body.is_a?(Hash)
+          parsed_body.delete("actionCode") # Remove deprecated actionCode from response
           env.body = transform_to_snake_case(parsed_body)
         end
       rescue JSON::ParserError

data/lib/authsignal/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Authsignal
-  VERSION = "3.0.0"
+  VERSION = "4.0.0"
 end

data/lib/authsignal.rb

@@ -3,10 +3,13 @@ require "faraday/retry"
 require "authsignal/version"
 require "authsignal/client"
 require "authsignal/configuration"
+require "authsignal/api_error"
 require "authsignal/middleware/json_response"
 require "authsignal/middleware/json_request"
 
 module Authsignal
+    NON_API_METHODS = [:setup, :configuration, :default_configuration]
+
     class << self
         attr_writer :configuration
 
@@ -52,8 +55,8 @@ module Authsignal
             handle_response(response)
         end
 
-        def delete_user_authenticator(user_id:, user_authenticator_id: )
-            response = Client.new.delete_user_authenticator(user_id: user_id, user_authenticator_id: user_authenticator_id)
+        def delete_authenticator(user_id:, user_authenticator_id: )
+            response = Client.new.delete_authenticator(user_id: user_id, user_authenticator_id: user_authenticator_id)
 
             handle_response(response)
         end
@@ -66,8 +69,8 @@ module Authsignal
             handle_response(response)
         end
 
-        def validate_challenge(token:, user_id: nil)
-            response = Client.new.validate_challenge(user_id: user_id, token: token)
+        def validate_challenge(token:, user_id: nil, action: nil)
+            response = Client.new.validate_challenge(user_id: user_id, token: token, action: action)
             
             handle_response(response)
         end
@@ -76,18 +79,35 @@ module Authsignal
 
         def handle_response(response)
             if response.success?
-                response.body
+                handle_success_response(response)
             else
                 handle_error_response(response)
             end
         end
 
+        def handle_success_response(response)
+            response.body.merge(success?: true)
+        end
+
         def handle_error_response(response)
             case response.body
             when Hash
-                response.body.merge({ status: response.status })
+                response.body.merge(status: response.status, success?: false)
             else
-                { status: response.status }
+                { status: response&.status || 500, success?: false }
+            end
+        end
+    end
+
+    methods = Authsignal.singleton_class.public_instance_methods(false)
+    (methods - NON_API_METHODS).each do |method|
+        define_singleton_method("#{method}!") do |*args, **kwargs|
+            send(method, *args, **kwargs).tap do |response|
+                status = response[:status]
+                err = response[:error]
+                desc = response[:error_description]
+
+                raise ApiError.new(err, status, err, desc) unless response[:success?]
             end
         end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authsignal-ruby
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - justinsoong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-14 00:00:00.000000000 Z
+date: 2024-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -100,6 +100,7 @@ files:
 - bin/console
 - bin/setup
 - lib/authsignal.rb
+- lib/authsignal/api_error.rb
 - lib/authsignal/client.rb
 - lib/authsignal/configuration.rb
 - lib/authsignal/middleware/json_request.rb