passageidentity 0.6.2 → 0.7.0

data/lib/passageidentity/client.rb

@@ -1,101 +1,113 @@
 # frozen_string_literal: true
 
-require_relative "auth"
-require_relative "user_api"
-require_relative "error"
-require_relative "version"
-require "rubygems"
-require_relative "../openapi_client"
+require 'rubygems'
+require_relative 'auth'
+require_relative 'user_api'
+require_relative 'error'
+require_relative 'version'
+require_relative '../openapi_client'
 
 module Passage
   COOKIE_STRATEGY = 0
   HEADER_STRATEGY = 1
 
-  EMAIL_CHANNEL = "email"
-  PHONE_CHANNEL = "phone"
+  EMAIL_CHANNEL = 'email'
+  PHONE_CHANNEL = 'phone'
 
+  # The Passage::Client class provides methods for interacting with Passage
   class Client
-    attr_reader :auth
-    attr_reader :user
+    attr_reader :auth, :user
 
-    def initialize(app_id:, api_key: "", auth_strategy: COOKIE_STRATEGY)
+    extend Gem::Deprecate
+
+    def initialize(app_id:, api_key: '', auth_strategy: COOKIE_STRATEGY)
       @app_id = app_id
       @api_key = api_key
 
       # check for valid auth strategy
       unless [COOKIE_STRATEGY, HEADER_STRATEGY].include? auth_strategy
-        raise PassageError.new(message: "invalid auth strategy.")
+        raise PassageError.new(
+          status_code: 400,
+          body: {
+            error: 'Invalid auth strategy',
+            code: 'invalid_argument'
+          }
+        )
       end
+
       @auth_strategy = auth_strategy
 
+      header_params = { 'Passage-Version' => "passage-ruby #{Passage::VERSION}" }
+      header_params['Authorization'] = "Bearer #{@api_key}" if @api_key != ''
+
+      @req_opts = {}
+      @req_opts[:header_params] = header_params
+      @req_opts[:debug_auth_names] = ['header']
+
       # initialize auth class
-      @auth = Passage::Auth.new(@app_id, @auth_strategy)
+      @auth = Passage::Auth.new(@app_id, @api_key, @auth_strategy)
 
       # initialize user class
       @user = Passage::UserAPI.new(@app_id, @api_key)
+
+      @magic_links_client = OpenapiClient::MagicLinksApi.new
     end
 
-    def get_app()
-      begin
-        client = OpenapiClient::AppsApi.new
-        return client.get_app(@app_id).app
-      rescue => e
-        raise e
-      end
+    # rubocop:disable Naming/AccessorMethodName
+    def get_app
+      client = OpenapiClient::AppsApi.new
+      client.get_app(@app_id).app
+    rescue StandardError => e
+      raise e
     end
+    # rubocop:enable Naming/AccessorMethodName
 
+    # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def create_magic_link(
-      user_id: "",
-      email: "",
-      phone: "",
-      channel: "",
+      user_id: '',
+      email: '',
+      phone: '',
+      channel: '',
       send: false,
-      magic_link_path: "",
-      redirect_url: "",
-      language: "",
+      magic_link_path: '',
+      redirect_url: '',
+      language: '',
       ttl: 60,
-      type: "login"
+      type: 'login'
     )
-      magic_link_req = {}
-      magic_link_req["user_id"] = user_id unless user_id.empty?
-      magic_link_req["email"] = email unless email.empty?
-      magic_link_req["phone"] = phone unless phone.empty?
+      args = {}
+      args['user_id'] = user_id unless user_id.empty?
+      args['email'] = email unless email.empty?
+      args['phone'] = phone unless phone.empty?
 
-      # check to see if the channel specified is valid before sending it off to the server
       unless [PHONE_CHANNEL, EMAIL_CHANNEL].include? channel
         raise PassageError.new(
-                message:
-                  "channel: must be either Passage::EMAIL_CHANNEL or Passage::PHONE_CHANNEL"
-              )
+          message:
+            'channel: must be either Passage::EMAIL_CHANNEL or Passage::PHONE_CHANNEL'
+        )
       end
-      magic_link_req["channel"] = channel unless channel.empty?
-      magic_link_req["send"] = send
-      magic_link_req[
-        "magic_link_path"
-      ] = magic_link_path unless magic_link_path.empty?
-      magic_link_req["redirect_url"] = redirect_url unless redirect_url.empty?
-      magic_link_req["ttl"] = ttl unless ttl == 0
-      magic_link_req["type"] = type
+
+      args['channel'] = channel unless channel.empty?
+      args['type'] = type
+      args['send'] = send
+
+      args['language'] = language unless language.empty?
+      args['magic_link_path'] = magic_link_path unless magic_link_path.empty?
+      args['redirect_url'] = redirect_url unless redirect_url.empty?
+      args['ttl'] = ttl unless ttl.zero?
 
       begin
-        gemspec = File.join(__dir__, "../../passageidentity.gemspec")
-        spec = Gem::Specification.load(gemspec)
-        header_params = { "Passage-Version" => "passage-ruby #{Passage::VERSION}" }
-        header_params["Authorization"] = "Bearer #{@api_key}" if @api_key != ""
-        
-        opts = {}
-        opts[:header_params] = header_params
-        opts[:debug_auth_names] = ["header"]
-
-        client = OpenapiClient::MagicLinksApi.new
-        return client.create_magic_link(@app_id, magic_link_req, opts).magic_link
+        @magic_links_client.create_magic_link(@app_id, args, @req_opts).magic_link
       rescue Faraday::Error => e
         raise PassageError.new(
-                message: "failed to create Passage Magic Link",
-                status_code: e.response[:status],
-                body: e.response[:body]
-              )
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
+    # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    deprecate(:create_magic_link, 'Passage::Auth.create_magic_link', 2025, 1)
+    deprecate(:get_app, :none, 2025, 1)
   end
 end

data/lib/passageidentity/error.rb

@@ -1,24 +1,50 @@
-require "net/http"
+# frozen_string_literal: true
+
+require 'net/http'
 
 module Passage
+  # PassageError is a custom error class for handling errors
   class PassageError < StandardError
-    attr_reader :status_code
-    attr_reader :status_text
-    attr_reader :message
-    attr_reader :error
+    attr_reader :status_code, :error_code, :message, :status_text, :error
+
+    def initialize(message: nil, status_code: nil, body: {})
+      # Ensure body is a hash
+      body = {} if body.nil?
 
-    def initialize(message:, status_code: nil, body: nil)
-      @message = message
+      body = symbolize_keys(body)
       @status_code = status_code
-      @status_text =
-        (
-          if status_code.nil?
-            nil
-          else
-            Net::HTTPResponse::CODE_TO_OBJ[status_code.to_s]
-          end
-        )
-      @error = body.nil? ? nil : body["error"]
+      @error_code = body[:code]
+      # Message precedence: explicit message > body error > default message
+      @message = determine_message(message, body)
+      # Determine status text from status code if available
+      @status_text = determine_status_text(status_code)
+      # Set error field based on message
+      @error = @message
+
+      super(@message)
+    end
+
+    private
+
+    def determine_message(message, body)
+      return message if message
+
+      return body[:error] if body[:error]
+
+      'Unknown error occurred'
+    end
+
+    def determine_status_text(code)
+      return nil if code.nil?
+
+      status_code_str = code.to_s
+      Net::HTTPResponse::CODE_TO_OBJ[status_code_str]
+    rescue StandardError
+      nil
+    end
+
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
     end
   end
 end

data/lib/passageidentity/user_api.rb

@@ -1,7 +1,14 @@
-require_relative "client"
+# frozen_string_literal: true
+
+require 'rubygems/deprecate'
+require_relative 'client'
 
 module Passage
+  # The UserAPI class provides methods for interacting with Passage Users
   class UserAPI
+    extend Gem::Deprecate
+
+    # rubocop:disable Metrics/AbcSize
     # This class will require an API key
     def initialize(app_id, api_key)
       @app_id = app_id
@@ -9,41 +16,30 @@ module Passage
       @user_client = OpenapiClient::UsersApi.new
       @user_device_client = OpenapiClient::UserDevicesApi.new
 
-      header_params = { "Passage-Version" => "passage-ruby #{Passage::VERSION}"}
-      header_params["Authorization"] = "Bearer #{@api_key}" if @api_key != ""
-      
+      header_params = { 'Passage-Version' => "passage-ruby #{Passage::VERSION}" }
+      header_params['Authorization'] = "Bearer #{@api_key}" if @api_key != ''
+
       @req_opts = {}
       @req_opts[:header_params] = header_params
-      @req_opts[:debug_auth_names] = ["header"]
-      
+      @req_opts[:debug_auth_names] = ['header']
     end
 
     def get(user_id:)
-      user_exists?(user_id)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
 
       begin
         response = @user_client.get_user(@app_id, user_id, @req_opts)
-        user = response.user
-        return user
+        response.user
       rescue Faraday::Error => e
-        if e.is_a? Faraday::ResourceNotFound
-          raise PassageError.new(
-                  message: "Passage User with ID \"#{user_id}\" does not exist",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        else
-          raise PassageError.new(
-                  message: "failed to get Passage User.",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        end
+        raise PassageError.new(
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
     def get_by_identifier(user_identifier:)
-      identifier_exists?(user_identifier)
+      raise ArgumentError, 'identifier is required.' unless user_identifier && !user_identifier.empty?
 
       begin
         @req_opts[:limit] = 1
@@ -51,209 +47,172 @@ module Passage
         response = @user_client.list_paginated_users(@app_id, @req_opts)
         users = response.users
 
-        if users.length() == 0
+        if users.empty?
           raise PassageError.new(
-                  message: "Passage User with identifer \"#{user_identifier}\" does not exist",
-                  status_code: 404,
-                  body: "user_not_found"
-                )
+            status_code: 404,
+            body: {
+              error: 'User not found.',
+              code: 'user_not_found'
+            }
+          )
         end
-        return get(user_id: users.first().id)
+        get(user_id: users.first.id)
       rescue Faraday::Error => e
-        if e.is_a? Faraday::ResourceNotFound
-          raise PassageError.new(
-                  message: "Passage User with identifer \"#{user_identifier}\" does not exist",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        else
-          raise PassageError.new(
-                  message: "failed to get Passage User.",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        end
+        raise PassageError.new(
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
     def activate(user_id:)
-      user_exists?(user_id)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
 
       begin
         response = @user_client.activate_user(@app_id, user_id, @req_opts)
-        return response.user
+        response.user
       rescue Faraday::Error => e
-        if e.is_a? Faraday::ResourceNotFound
-          raise PassageError.new(
-                  message: "Passage User with ID \"#{user_id}\" does not exist",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        else
-          raise PassageError.new(
-                  message: "failed to activate Passage User.",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        end
+        raise PassageError.new(
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
     def deactivate(user_id:)
-      user_exists?(user_id)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
 
       begin
         response = @user_client.deactivate_user(@app_id, user_id, @req_opts)
-        return response.user
+        response.user
       rescue Faraday::Error => e
-        if e.is_a? Faraday::ResourceNotFound
-          raise PassageError.new(
-                  message: "Passage User with ID \"#{user_id}\" does not exist",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        else
-          raise PassageError.new(
-                  message: "failed to deactivate Passage User.",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        end
+        raise PassageError.new(
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
-    def update(user_id:, email: "", phone: "", user_metadata: {})
-      user_exists?(user_id)
+    def update(user_id:, email: '', phone: '', user_metadata: {})
+      warn '[DEPRECATED] the `update` method parameters will change to `user_id: string, ' \
+           'options: UpdateUserArgs`. Parameters will change on or after 2025-1.'
 
       updates = {}
-      updates["email"] = email unless email.empty?
-      updates["phone"] = phone unless phone.empty?
-      updates["user_metadata"] = user_metadata unless user_metadata.empty?
-      begin
-        response = @user_client.update_user(@app_id, user_id, updates, @req_opts)
-        return response.user
-      rescue Faraday::Error => e
-        if e.is_a? Faraday::ResourceNotFound
-          raise PassageError.new(
-                  message: "Passage User with ID \"#{user_id}\" does not exist",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        else
-          raise PassageError.new(
-                  "failed to update Passage User",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        end
-      end
+      updates['email'] = email unless email.empty?
+      updates['phone'] = phone unless phone.empty?
+      updates['user_metadata'] = user_metadata unless user_metadata.empty?
+
+      update_v2(user_id: user_id, options: updates)
     end
 
-    def create(email: "", phone: "", user_metadata: {})
+    def create(email: '', phone: '', user_metadata: {})
+      warn '[DEPRECATED] the `create` method parameters will change to `args: CreateUserArgs`.' \
+      'Parameters will change on or after 2025-1.'
+
       create = {}
-      create["email"] = email unless email.empty?
-      create["phone"] = phone unless phone.empty?
-      create["user_metadata"] = user_metadata unless user_metadata.empty?
-      begin
-        response = @user_client.create_user(@app_id, create, @req_opts)
-        return response.user
-      rescue Faraday::Error => e
-        raise PassageError.new(
-                "failed to create Passage User",
-                status_code: e.response[:status],
-                body: e.response[:body]
-              )
-      end
+      create['email'] = email unless email.empty?
+      create['phone'] = phone unless phone.empty?
+      create['user_metadata'] = user_metadata unless user_metadata.empty?
+
+      create_v2(args: create)
     end
 
     def delete(user_id:)
-      user_exists?(user_id)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
 
       begin
-        response = @user_client.delete_user(@app_id, user_id, @req_opts)
-        return true
+        @user_client.delete_user(@app_id, user_id, @req_opts)
+        true
       rescue Faraday::Error => e
-        if e.is_a? Faraday::ResourceNotFound
-          raise PassageError.new(
-                  "passage User with ID \"#{user_id}\" does not exist",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        else
-          raise PassageError.new(
-                  "failed to delete Passage User",
-                  status_code: e.response[:status],
-                  body: e.response[:body]
-                )
-        end
+        raise PassageError.new(
+          'failed to delete Passage User',
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
-    def delete_device(user_id:, device_id:)
-      user_exists?(user_id)
-      device_exists?(device_id)
+    def revoke_device(user_id:, device_id:)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
+      raise ArgumentError, 'device_id is required.' unless device_id && !device_id.empty?
 
       begin
-        response = @user_device_client.delete_user_devices(@app_id, user_id, device_id, @req_opts)
-        return true
+        @user_device_client.delete_user_devices(@app_id, user_id, device_id, @req_opts)
       rescue Faraday::Error => e
         raise PassageError.new(
-                "failed to delete Passage User Device",
-                status_code: e.response[:status],
-                body: e.response[:body]
-              )
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
+    def delete_device(user_id:, device_id:)
+      revoke_device(user_id: user_id, device_id: device_id)
+      true
+    end
+
     def list_devices(user_id:)
-      user_exists?(user_id)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
 
       begin
         response = @user_device_client.list_user_devices(@app_id, user_id, @req_opts)
-        return response.devices
+        response.devices
       rescue Faraday::Error => e
         raise PassageError.new(
-                "failed to delete Passage User Device",
-                status_code: e.response[:status],
-                body: e.response[:body]
-              )
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
     def signout(user_id:)
-      warn "[DEPRECATION] `user.signout()` is deprecated.  Please use `auth.revoke_user_refresh_tokens()` instead."
-      user_exists?(user_id)
+      revoke_refresh_tokens(user_id: user_id)
+      true
+    end
+
+    def revoke_refresh_tokens(user_id:)
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
+
       begin
         tokens_client = OpenapiClient::TokensApi.new
-        response = tokens_client.revoke_user_refresh_tokens(@app_id, user_id, @req_opts)
-        return true
+        tokens_client.revoke_user_refresh_tokens(@app_id, user_id, @req_opts)
       rescue Faraday::Error => e
         raise PassageError.new(
-                "failed to revoke user's refresh tokens",
-                status_code: e.response[:status],
-                body: e.response[:body]
-              )
+          status_code: e.response[:status],
+          body: e.response[:body]
+        )
       end
     end
 
     private
 
-    def user_exists?(user_id)
-      if user_id.to_s.empty?
-        raise PassageError.new(message: "must supply a valid user_id")
-      end
-    end
+    def create_v2(args: {})
+      raise ArgumentError, 'At least one of args.email or args.phone is required.' unless args['phone'] || args['email']
 
-    def identifier_exists?(identifier)
-      if identifier.to_s.empty?
-        raise PassageError.new(message: "must supply a valid identifier")
-      end
+      response = @user_client.create_user(@app_id, args, @req_opts)
+      response.user
+    rescue Faraday::Error => e
+      raise PassageError.new(
+        status_code: e.response[:status],
+        body: e.response[:body]
+      )
     end
 
-    def device_exists?(device_id)
-      if device_id.to_s.empty?
-        raise PassageError.new(message: "must supply a valid device_id")
-      end
+    def update_v2(user_id:, options: {})
+      raise ArgumentError, 'user_id is required.' unless user_id && !user_id.empty?
+      raise ArgumentError, 'options are required.' if options.empty?
+
+      response = @user_client.update_user(@app_id, user_id, options, @req_opts)
+      response.user
+    rescue Faraday::Error => e
+      raise PassageError.new(
+        status_code: e.response[:status],
+        body: e.response[:body]
+      )
     end
+    # rubocop:enable Metrics/AbcSize
+
+    deprecate(:signout, :revoke_refresh_tokens, 2025, 1)
+    deprecate(:delete_device, :revoke_device, 2025, 1)
   end
 end

data/lib/passageidentity/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Passage
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 end

data/lib/passageidentity.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
-require "faraday"
+require 'bundler/setup'
 
-require_relative "passageidentity/client"
+require 'faraday'
 
+require_relative 'passageidentity/client'
+
+# This file defines the Passage module and requires necessary dependencies.
+# The Passage module serves as a namespace for the Passage Identity functionality.
 module Passage
 end