kinde_sdk 1.6.6 → 1.7.0

data/lib/kinde_sdk/client/roles.rb

@@ -0,0 +1,218 @@
+module KindeSdk
+  class Client
+    module Roles
+      # Get all roles for the authenticated user
+      # Matches the JavaScript SDK API: getRoles(options?)
+      # Implements smart fallback: uses API automatically if token claims are empty
+      #
+      # @param options [Hash] Options for retrieving roles
+      # @option options [Boolean] :force_api (false) If true, calls the API to get fresh roles,
+      #   otherwise extracts from token claims. Will auto-fallback to API if token claims are empty.
+      # @option options [Symbol] :token_type (:access_token) The token type to use for soft check (:access_token or :id_token)
+      # @return [Array] Array of role objects with id, name, and key
+      # @example
+      #   # Soft check (from token) with auto-fallback to API if empty
+      #   client.get_roles
+      #   # => [{ id: "role_123", name: "Admin", key: "admin" }]
+      #
+      #   # Hard check (from API - always fresh)
+      #   client.get_roles(force_api: true)
+      #   # => [{ id: "role_123", name: "Admin", key: "admin" }]
+      def get_roles(options = {})
+        # Handle legacy positional argument for backward compatibility
+        if options.is_a?(Symbol)
+          options = { token_type: options }
+        end
+        
+        # Extract options with defaults - use member variable if not overridden
+        force_api = options[:force_api] || @force_api || false
+        token_type = options[:token_type] || :access_token
+
+        # Smart fallback logic matching js-utils exactly
+        # Check if we have role claims first (efficiency optimization)
+        roles_claim = get_claim("roles", token_type)
+        
+        if force_api || !roles_claim&.dig(:value)&.any?
+          # Use API if explicitly requested OR if token claims are empty
+          log_info("Using API for roles: force_api=#{force_api}, empty_claims=#{!roles_claim&.dig(:value)&.any?}")
+          return get_roles_from_api
+        end
+
+        # Use token claims (soft check)
+        get_roles_from_token(token_type)
+      end
+
+      # Check if user has specific roles
+      # Matches JavaScript SDK hasRoles functionality
+      #
+      # @param role_keys [Array<String>, String] Array of role keys to check, or single role key
+      # @param options [Hash] Options for retrieving roles (same as get_roles)
+      # @return [Boolean] True if user has all specified roles, false otherwise
+      def has_roles?(role_keys, options = {})
+        return true if role_keys.nil? || (role_keys.respond_to?(:empty?) && role_keys.empty?)
+        
+        begin
+          user_roles = get_roles(options)
+          role_keys_array = Array(role_keys)
+          user_role_keys = user_roles.map { |role| role[:key] || role['key'] }.compact
+          
+          result = role_keys_array.all? { |role_key| user_role_keys.include?(role_key.to_s) }
+          log_debug("Role check for #{role_keys_array}: #{result} (user has: #{user_role_keys})")
+          result
+        rescue StandardError => e
+          log_error("Error checking roles: #{e.message}")
+          false
+        end
+      end
+
+      # PHP SDK compatible alias for get_roles with hard check
+      # Matches PHP: $client->getRoles()
+      #
+      # @return [Array] Array of role objects
+      def getRoles
+        # Use client's force_api setting, default to true for PHP SDK compatibility
+        force_api_setting = @force_api.nil? ? true : @force_api
+        get_roles(force_api: force_api_setting)
+      end
+
+      # JavaScript SDK compatible alias
+      alias_method :hasRoles, :has_roles?
+
+      private
+
+      # Get roles from token claims (soft check)
+      # Matches JavaScript logic: token.roles || token["x-hasura-roles"] || []
+      # Includes helpful warnings like js-utils
+      #
+      # @param token_type [Symbol] The token type to use
+      # @return [Array] Array of role objects
+      def get_roles_from_token(token_type = :access_token)
+        # First try standard roles claim
+        roles = get_claim("roles", token_type)&.dig(:value)
+        
+        # Fallback to Hasura-specific roles (matches JS SDK)
+        if roles.nil? || roles.empty?
+          roles = get_claim("x-hasura-roles", token_type)&.dig(:value)
+        end
+        
+        # Warning message matching js-utils behavior
+        if roles.nil? || roles.empty?
+          log_warning("No roles found in token. Ensure roles have been included in the token customisation within the application settings.")
+          return []
+        end
+
+        # Ensure consistent format - normalize all role data
+        normalize_roles(roles)
+      end
+
+      # Get roles from API (hard check)
+      # Matches JavaScript API endpoint and data extraction exactly
+      #
+      # @return [Array] Array of role objects
+      def get_roles_from_api
+        unless token_store.bearer_token
+          log_warning("No bearer token available for API call")
+          return []
+        end
+
+        begin
+          # Use the same pagination pattern as getAllEntitlements
+          all_roles = paginate_all_results('roles') do |starting_after|
+            user_roles(page_size: 100, starting_after: starting_after)
+          end
+
+          # Extract and normalize role data (matches js-utils format exactly)
+          normalized_roles = normalize_roles(all_roles)
+          log_debug("Retrieved #{normalized_roles.count} roles from API")
+          normalized_roles
+        rescue KindeSdk::APIError => e
+          log_error("API Error getting roles: #{e.message}")
+          # Graceful fallback to token-based roles (matches JS behavior)
+          log_info("Falling back to token-based roles due to API error")
+          get_roles_from_token
+        rescue StandardError => e
+          log_error("Unexpected error getting roles from API: #{e.message}")
+          # Graceful fallback to token-based roles
+          log_info("Falling back to token-based roles due to unexpected error")
+          get_roles_from_token
+        end
+      end
+
+      # Normalize role data to consistent format
+      # Ensures we always return { id:, name:, key: } format like js-utils
+      #
+      # @param roles [Array] Raw role data from token or API
+      # @return [Array] Normalized role objects
+      def normalize_roles(roles)
+        return [] if roles.nil?
+
+        Array(roles).map do |role|
+          if role.is_a?(Hash) || role.respond_to?(:id)
+            {
+              id: extract_field(role, :id),
+              name: extract_field(role, :name),
+              key: extract_field(role, :key)
+            }
+          else
+            # Handle string-only roles (fallback)
+            role_str = role.to_s
+            {
+              id: nil,
+              name: role_str,
+              key: role_str
+            }
+          end
+        end.compact
+      end
+
+      # Helper to extract field from hash or object
+      def extract_field(item, field)
+        if item.respond_to?(field)
+          item.public_send(field)
+        elsif item.is_a?(Hash)
+          item[field] || item[field.to_s]
+        else
+          nil
+        end
+      end
+
+      # Configurable logging that works with or without Rails
+      # Supports multiple log levels for better debugging
+      def log_error(message)
+        write_log(:error, message)
+      end
+
+      def log_warning(message)
+        write_log(:warn, message)
+      end
+
+      def log_info(message)
+        write_log(:info, message)
+      end
+
+      def log_debug(message)
+        write_log(:debug, message)
+      end
+
+      def write_log(level, message)
+        formatted_message = "[KindeSdk::Roles] #{message}"
+        
+        if defined?(Rails) && Rails.logger
+          Rails.logger.public_send(level, formatted_message)
+        elsif @logger && @logger.respond_to?(level)
+          @logger.public_send(level, formatted_message)
+        elsif respond_to?(:logger) && logger && logger.respond_to?(level)
+          logger.public_send(level, formatted_message)
+        else
+          # Fallback based on level
+          case level
+          when :error, :warn
+            $stderr.puts formatted_message
+          when :info, :debug
+            $stdout.puts formatted_message if ENV['KINDE_DEBUG']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kinde_sdk/client.rb

@@ -2,9 +2,15 @@ require_relative '../../kinde_api/lib/kinde_api'
 require_relative 'token_manager'
 require_relative 'token_store'
 require_relative 'current'
+require_relative 'errors'
+require_relative 'internal/frontend_client'
+require_relative 'client/feature_flags'
+require_relative 'client/permissions'
+require_relative 'client/roles'
+require_relative 'client/entitlements'
 
 module KindeSdk
-  # Constants for portal page navigation
+  # Constants for portal page navigation - matches PHP SDK exactly
   module PortalPage
     ORGANIZATION_DETAILS = 'organization_details'
     ORGANIZATION_MEMBERS = 'organization_members'
@@ -17,13 +23,16 @@ module KindeSdk
   class Client
     include FeatureFlags
     include Permissions
+    include Roles
+    include Entitlements
 
-    attr_accessor :kinde_api_client, :auto_refresh_tokens, :token_store
+    attr_accessor :kinde_api_client, :auto_refresh_tokens, :token_store, :force_api
 
-    def initialize(sdk_api_client, tokens_hash, auto_refresh_tokens)
+    def initialize(sdk_api_client, tokens_hash, auto_refresh_tokens, force_api = false)
       @kinde_api_client = sdk_api_client
       @auto_refresh_tokens = auto_refresh_tokens
       @token_store = TokenManager.create_store(tokens_hash)
+      @force_api = force_api
 
       # refresh the token if it's expired and auto_refresh_tokens is enabled
       refresh_token if auto_refresh_tokens && TokenManager.token_expired?(@token_store)
@@ -150,8 +159,237 @@ module KindeSdk
       oauth_api
     end
 
+    # Frontend API access - Internal use only
+    # Uses user access tokens instead of M2M tokens
+    def frontend
+      @frontend_client ||= KindeSdk::Internal::FrontendClient.new(@token_store, KindeSdk.config.domain)
+    end
+
+    # Public SDK methods that use Frontend API internally
+    
+    # Get entitlements for the authenticated user with pagination support.
+    #
+    # @param page_size [Integer] Number of results per page (default: 10)
+    # @param starting_after [String] The ID to start after for pagination
+    # @return [OpenStruct] Response containing entitlements data
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def entitlements(page_size: 10, starting_after: nil)
+      frontend.get_entitlements(page_size: page_size, starting_after: starting_after)
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch entitlements: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch entitlements: #{e.message}"
+    end
+
+    # Get all entitlements for the authenticated user, handling pagination automatically.
+    #
+    # @return [Array] All entitlements
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def getAllEntitlements
+      unless token_store.bearer_token
+        raise KindeSdk::APIError, 'User must be authenticated to get entitlements'
+      end
+
+      paginate_all_results('entitlements') { |starting_after| entitlements(page_size: 100, starting_after: starting_after) }
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch all entitlements: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch all entitlements: #{e.message}"
+    end
+
+    # Ruby-style alias for getAllEntitlements
+    alias_method :all_entitlements, :getAllEntitlements
+
+    # Get a specific entitlement by key.
+    #
+    # @param key [String] The entitlement key to retrieve
+    # @return [OpenStruct, nil] The entitlement response or nil if not found
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def entitlement(key)
+      frontend.get_entitlement(key)
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch entitlement for #{key}: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch entitlement: #{e.message}"
+    end
+
+    # PHP SDK compatible alias for entitlement
+    #
+    # @param key [String] The entitlement key to retrieve
+    # @return [OpenStruct, nil] The entitlement response or nil if not found
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def getEntitlement(key)
+      # Find the specific entitlement from all entitlements (like PHP SDK does)
+      entitlements = getAllEntitlements
+      
+      entitlements.find { |entitlement| entitlement.feature_key == key }
+    rescue StandardError => e
+      Rails.logger.error("Failed to get entitlement for #{key}: #{e.message}")
+      raise KindeSdk::APIError, "Unable to get entitlement: #{e.message}"
+    end
+
+    # Check if the user has a specific entitlement.
+    #
+    # @param feature_key [String] The entitlement key to check
+    # @return [Boolean] True if the user has the entitlement, false otherwise
+    def has_entitlement?(feature_key)
+      entitlement_response = entitlement(feature_key)
+      entitlement_response&.data&.entitlement.present?
+    rescue StandardError => e
+      Rails.logger.error("Error checking entitlement for #{feature_key}: #{e.message}")
+      false
+    end
+
+    # PHP SDK compatible alias for has_entitlement?
+    #
+    # @param key [String] The entitlement key to check
+    # @return [Boolean] True if the user has the entitlement, false otherwise
+    def hasEntitlement(key)
+      getEntitlement(key) != nil
+    rescue StandardError => e
+      Rails.logger.error("Error checking entitlement for #{key}: #{e.message}")
+      false
+    end
+
+    # Get the maximum limit for a specific entitlement.
+    #
+    # @param key [String] The entitlement key
+    # @return [Integer, nil] The maximum limit or nil if not found
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def getEntitlementLimit(key)
+      entitlement = getEntitlement(key)
+      entitlement ? entitlement.entitlement_limit_max : nil
+    rescue StandardError => e
+      Rails.logger.error("Error getting entitlement limit for #{key}: #{e.message}")
+      nil
+    end
+
+    # Ruby-style alias for getEntitlementLimit
+    alias_method :entitlement_limit, :getEntitlementLimit
+
+    # Get user feature flags with pagination support.
+    #
+    # @param page_size [Integer] Number of results per page (default: 10)
+    # @param starting_after [String] The ID to start after for pagination
+    # @return [OpenStruct] Response containing feature flags data
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def user_feature_flags(page_size: 10, starting_after: nil)
+      frontend.get_feature_flags(page_size: page_size, starting_after: starting_after)
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch feature flags: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch feature flags: #{e.message}"
+    end
+
+    # Get user permissions with pagination support.
+    #
+    # @param page_size [Integer] Number of results per page (default: 10)
+    # @param starting_after [String] The ID to start after for pagination
+    # @return [OpenStruct] Response containing permissions data
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def user_permissions(page_size: 10, starting_after: nil)
+      frontend.get_user_permissions(page_size: page_size, starting_after: starting_after)
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch permissions: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch permissions: #{e.message}"
+    end
+
+    # Get user properties with pagination support.
+    #
+    # @param page_size [Integer] Number of results per page (default: 10)
+    # @param starting_after [String] The ID to start after for pagination
+    # @return [OpenStruct] Response containing properties data
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def user_properties(page_size: 10, starting_after: nil)
+      frontend.get_user_properties(page_size: page_size, starting_after: starting_after)
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch properties: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch properties: #{e.message}"
+    end
+
+    # Get user roles with pagination support.
+    #
+    # @param page_size [Integer] Number of results per page (default: 10)
+    # @param starting_after [String] The ID to start after for pagination
+    # @return [OpenStruct] Response containing roles data
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def user_roles(page_size: 10, starting_after: nil)
+      frontend.get_user_roles(page_size: page_size, starting_after: starting_after)
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch roles: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch roles: #{e.message}"
+    end
+
+    # Generate a URL to the user profile portal.
+    #
+    # @param return_url [String] URL to redirect to after completing the profile flow
+    # @param sub_nav [String] Sub-navigation section to display (defaults to 'profile')
+    # @return [Hash] A hash containing the generated URL
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def portal_link(return_url:, page: PortalPage::PROFILE)
+      frontend.get_portal_link(subnav: page, return_url: return_url)
+    rescue StandardError => e
+      Rails.logger.error("Failed to get portal link: #{e.message}")
+      raise KindeSdk::APIError, "Unable to get portal link: #{e.message}"
+    end
+
+    # PHP SDK compatible portal URL generation method.
+    #
+    # @param return_url [String] URL to redirect to after completing the profile flow
+    # @param sub_nav [String] Sub-navigation section to display (defaults to 'profile')
+    # @return [Hash] A hash containing the generated URL
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    # @raise [ArgumentError] If the return_url is not an absolute URL
+    def generatePortalUrl(return_url, sub_nav = PortalPage::PROFILE)
+      unless token_store.bearer_token
+        raise KindeSdk::APIError, 'generatePortalUrl: Access Token not found'
+      end
+
+      unless return_url.start_with?('http')
+        raise ArgumentError, 'generatePortalUrl: returnUrl must be an absolute URL'
+      end
+
+      frontend.get_portal_link(subnav: sub_nav, return_url: return_url)
+    rescue StandardError => e
+      Rails.logger.error("Failed to generate portal URL: #{e.message}")
+      raise KindeSdk::APIError, "Unable to generate portal URL: #{e.message}"
+    end
+
+    # Get enhanced user profile information.
+    #
+    # @return [OpenStruct] Enhanced user profile data
+    # @raise [KindeSdk::APIError] If the user is not authenticated or API request fails
+    def enhanced_user_profile
+      frontend.get_user_profile_v2
+    rescue StandardError => e
+      Rails.logger.error("Failed to fetch enhanced profile: #{e.message}")
+      raise KindeSdk::APIError, "Unable to fetch enhanced profile: #{e.message}"
+    end
+
     private
 
+    # Generic pagination helper for all paginated API calls
+    #
+    # @param data_key [String] The key in the response data containing the array of results
+    # @param block [Proc] Block that makes the API call with starting_after parameter
+    # @return [Array] All paginated results
+    def paginate_all_results(data_key, &block)
+      all_results = []
+      starting_after = nil
+      
+      loop do
+        response = block.call(starting_after)
+        current_results = response&.data&.public_send(data_key) || []
+        all_results.concat(current_results)
+        
+        metadata = response&.metadata
+        has_more = metadata&.has_more
+        
+        break unless has_more && current_results.any?
+        
+        starting_after = metadata&.next_page_starting_after
+        break unless starting_after
+      end
+      
+      all_results
+    end
+
     def init_instance_api(api_klass)
       
       instance = api_klass.new(kinde_api_client)
@@ -169,5 +407,6 @@ module KindeSdk
       end
       instance
     end
+
   end
 end

data/lib/kinde_sdk/configuration.rb

@@ -20,6 +20,7 @@ module KindeSdk
     attr_accessor :oauth_client
     attr_accessor :pkce_enabled
     attr_accessor :auto_refresh_tokens
+    attr_accessor :force_api
 
     def initialize
       @authorize_url = '/oauth2/auth'
@@ -32,6 +33,7 @@ module KindeSdk
       @scope = 'openid offline email profile'
       @pkce_enabled = true
       @auto_refresh_tokens = true
+      @force_api = false
 
       yield(self) if block_given?
     end

data/lib/kinde_sdk/errors.rb

@@ -0,0 +1,7 @@
+module KindeSdk
+    class Error < StandardError; end
+    class APIError < Error; end
+    class AuthenticationError < APIError; end
+    class AuthorizationError < APIError; end
+    class RateLimitError < APIError; end
+  end

data/lib/kinde_sdk/internal/frontend_client.rb

@@ -0,0 +1,111 @@
+require 'httparty'
+require 'json'
+require 'ostruct'
+
+module KindeSdk
+  module Internal
+    class FrontendClient
+      include HTTParty
+      
+      def initialize(token_store, domain)
+        @token_store = token_store
+        @domain = domain
+        @base_uri = "#{domain}/account_api/v1"
+      end
+
+      def get_entitlements(page_size: 10, starting_after: nil)
+        make_request('/entitlements', {
+          page_size: page_size,
+          starting_after: starting_after
+        }.compact)
+      end
+
+      def get_entitlement(key)
+        make_request("/entitlement", { key: key })
+      end
+
+      def get_user_permissions(page_size: 10, starting_after: nil)
+        make_request('/permissions', {
+          page_size: page_size,
+          starting_after: starting_after
+        }.compact)
+      end
+
+      def get_user_properties(page_size: 10, starting_after: nil)
+        make_request('/properties', {
+          page_size: page_size,
+          starting_after: starting_after
+        }.compact)
+      end
+
+      def get_user_roles(page_size: 10, starting_after: nil)
+        make_request('/roles', {
+          page_size: page_size,
+          starting_after: starting_after
+        }.compact)
+      end
+
+      def get_feature_flags(page_size: 10, starting_after: nil)
+        make_request('/feature_flags', {
+          page_size: page_size,
+          starting_after: starting_after
+        }.compact)
+      end
+
+      def get_portal_link(subnav: nil, return_url: nil)
+        make_request('/portal_link', {
+          subnav: subnav,
+          return_url: return_url
+        }.compact)
+      end
+
+      def get_user_profile_v2
+        url = "#{@domain}/oauth2/v2/user_profile"
+        
+        response = HTTParty.get(url, {
+          headers: {
+            'Authorization' => "Bearer #{@token_store.bearer_token}",
+            'Content-Type' => 'application/json'
+          }
+        })
+        
+        handle_response(response)
+      end
+
+      private
+
+      def make_request(endpoint, params = {})
+        url = "#{@base_uri}#{endpoint}"
+        
+        response = HTTParty.get(url, {
+          query: params,
+          headers: {
+            'Authorization' => "Bearer #{@token_store.bearer_token}",
+            'Content-Type' => 'application/json'
+          }
+        })
+        
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        case response.code
+        when 200
+          # Parse as OpenStruct for easy access while keeping it internal
+          JSON.parse(response.body, object_class: OpenStruct)
+        when 401
+          raise KindeSdk::AuthenticationError, "Invalid or expired token"
+        when 403
+          raise KindeSdk::AuthorizationError, "Insufficient permissions"
+        when 404
+          # For entitlements, return nil when not found (matches PHP SDK behavior)
+          nil
+        when 429
+          raise KindeSdk::RateLimitError, "Too many requests"
+        else
+          raise KindeSdk::APIError, "API request failed with status #{response.code}: #{response.body}"
+        end
+      end
+    end
+  end
+end

data/lib/kinde_sdk/version.rb

@@ -1,3 +1,3 @@
 module KindeSdk
-  VERSION = "1.6.6"
+  VERSION = "1.7.0"
 end

data/lib/kinde_sdk.rb

@@ -6,6 +6,7 @@ require "kinde_sdk/client/feature_flags"
 require "kinde_sdk/client/permissions"
 require "kinde_sdk/client"
 require "kinde_sdk/current"
+require "kinde_sdk/errors"
 require 'securerandom'
 require 'oauth2'
 require 'pkce_challenge'
@@ -16,7 +17,12 @@ require 'jwt'
 require 'openssl'
 require 'base64'
 
+
+
 module KindeSdk
+
+
+  
   class << self
     attr_accessor :config
 
@@ -47,6 +53,7 @@ module KindeSdk
         redirect_uri: redirect_uri,
         state: SecureRandom.hex,
         scope: @config.scope,
+        supports_reauth: "true"
       }.merge(**kwargs)
       return { url: @config.oauth_client(
         client_id: client_id,
@@ -110,9 +117,9 @@ module KindeSdk
     #  "token_type"=>"bearer"}
     #
     # @return [KindeSdk::Client]
-    def client(tokens_hash, auto_refresh_tokens = @config.auto_refresh_tokens)
+    def client(tokens_hash, auto_refresh_tokens = @config.auto_refresh_tokens, force_api = @config.force_api)
       sdk_api_client = api_client(tokens_hash[:access_token] || tokens_hash["access_token"])
-      KindeSdk::Client.new(sdk_api_client, tokens_hash, auto_refresh_tokens)
+      KindeSdk::Client.new(sdk_api_client, tokens_hash, auto_refresh_tokens, force_api)
     end
 
     def logout_url(logout_url: @config.logout_url, domain: @config.domain)