kinde_sdk 1.2.3 → 1.7.0

data/lib/kinde_sdk/client/permissions.rb

@@ -1,19 +1,210 @@
 module KindeSdk
   class Client
     module Permissions
-      def get_permissions(token_type = :access_token)
+      # Get all permissions for the authenticated user
+      # Matches the JavaScript SDK API: getPermissions(options?)
+      #
+      # @param options [Hash, Symbol] Options for retrieving permissions, or legacy token_type symbol
+      # @option options [Boolean] :force_api (false) If true, calls the API to get fresh permissions,
+      #   otherwise extracts from token claims. Useful for ensuring latest permissions but may incur additional API calls
+      # @option options [Symbol] :token_type (:access_token) The token type to use for soft check (:access_token or :id_token)
+      # @return [Hash] Hash containing org_code and permissions array
+      # @example
+      #   # Soft check (from token)
+      #   client.get_permissions
+      #   # => { org_code: "org_123", permissions: ["read:users", "write:posts"] }
+      #
+      #   # Hard check (from API)
+      #   client.get_permissions(force_api: true)
+      #   # => { org_code: "org_123", permissions: ["read:users", "write:posts", "admin:all"] }
+      #
+      #   # Legacy backward compatibility
+      #   client.get_permissions(:id_token)
+      #   # => { org_code: "org_123", permissions: ["read:users", "write:posts"] }
+      def get_permissions(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
+
+        if force_api
+          # Hard check - call API for fresh permissions
+          get_permissions_from_api
+        else
+          # Soft check - extract from token claims
+          get_permissions_from_token(token_type)
+        end
+      end
+
+      # Get a specific permission status
+      #
+      # @param permission [String] The permission key to check
+      # @param options [Hash] Options for retrieving permissions (same as get_permissions)
+      # @return [Hash] Hash containing org_code and is_granted status
+      def get_permission(permission, options = {})
+        permissions_data = get_permissions(options)
+        
+        {
+          org_code: permissions_data[:org_code],
+          is_granted: permissions_data[:permissions]&.include?(permission) || false
+        }
+      end
+
+      # Check if a permission is granted
+      #
+      # @param permission [String] The permission key to check
+      # @param options [Hash] Options for retrieving permissions
+      # @return [Boolean] True if permission is granted, false otherwise
+      def permission_granted?(permission, options = {})
+        get_permission(permission, options)[:is_granted]
+      end
+
+      # PHP SDK compatible alias for get_permissions with hard check
+      # Matches PHP: $client->getPermissions()
+      #
+      # @return [Hash] Hash containing org_code and permissions array
+      def getPermissions
+        # Use client's force_api setting, default to true for PHP SDK compatibility
+        force_api_setting = @force_api.nil? ? true : @force_api
+        get_permissions(force_api: force_api_setting)
+      end
+
+      # Get all permissions with automatic pagination (hard check)
+      # Matches PHP: $client->getAllPermissions()
+      #
+      # @return [Array] Array of permission keys
+      def getAllPermissions
+        # Use client's force_api setting, default to true for PHP SDK compatibility
+        force_api_setting = @force_api.nil? ? true : @force_api
+        permissions_data = get_permissions(force_api: force_api_setting)
+        permissions_data[:permissions] || []
+      end
+
+      # JavaScript SDK compatible alias
+      alias_method :all_permissions, :getAllPermissions
+
+      # Backward compatibility method - matches existing Ruby SDK API
+      def get_permissions_legacy(token_type = :access_token)
         get_claim("permissions", token_type)&.dig(:value)
       end
 
-      def get_permission(permission, token_type = :access_token)
+      private
+
+      # Get permissions from token claims (soft check)
+      # Matches JavaScript logic exactly: token.permissions || token["x-hasura-permissions"] || []
+      #
+      # @param token_type [Symbol] The token type to use
+      # @return [Hash] Hash containing org_code and permissions array
+      def get_permissions_from_token(token_type = :access_token)
+        # First try standard permissions claim
+        permissions = get_claim("permissions", token_type)&.dig(:value)
+        
+        # Fallback to Hasura-specific permissions (matches JS SDK)
+        if permissions.nil? || permissions.empty?
+          permissions = get_claim("x-hasura-permissions", token_type)&.dig(:value)
+        end
+        
+        # Final fallback to empty array
+        permissions ||= []
+
+        # Get org_code with same fallback pattern
+        org_code = get_claim("org_code", token_type)&.dig(:value)
+        if org_code.nil?
+          org_code = get_claim("x-hasura-org-code", token_type)&.dig(:value)
+        end
+
+        # Log warning if no permissions found (helpful for debugging)
+        if permissions.empty?
+          log_warning("No permissions found in token. This may be expected if user has no permissions assigned.")
+        end
+
         {
-          org_code: get_claim("org_code", token_type)&.dig(:value),
-          is_granted: permission_granted?(permission)
+          org_code: org_code,
+          permissions: permissions
         }
       end
 
-      def permission_granted?(permission, token_type = :access_token)
-        get_claim("permissions", token_type)&.dig(:value)&.include?(permission) || false
+      # Get permissions from API (hard check)
+      # Matches JavaScript API endpoint and data extraction exactly
+      #
+      # @return [Hash] Hash containing org_code and permissions array
+      def get_permissions_from_api
+        unless token_store.bearer_token
+          return {
+            org_code: nil,
+            permissions: []
+          }
+        end
+
+        begin
+          # Use the same pagination pattern as getAllEntitlements
+          all_permissions = paginate_all_results('permissions') do |starting_after|
+            user_permissions(page_size: 100, starting_after: starting_after)
+          end
+
+          # Extract permission keys (matches JS: data.permissions?.map((permission) => permission.key))
+          permission_keys = all_permissions.map do |permission|
+            # Handle both OpenStruct and Hash responses
+            permission.respond_to?(:key) ? permission.key : permission['key']
+          end.compact
+
+          # Extract org_code from API response or fallback to token
+          org_code = nil
+          if all_permissions.any?
+            first_permission = all_permissions.first
+            org_code = first_permission.respond_to?(:org_code) ? 
+                      first_permission.org_code : 
+                      first_permission['org_code']
+          end
+          
+          # Fallback to token if API doesn't provide org_code
+          org_code ||= get_claim("org_code", :access_token)&.dig(:value)
+
+          {
+            org_code: org_code,
+            permissions: permission_keys
+          }
+        rescue KindeSdk::APIError => e
+          log_error("API Error getting permissions: #{e.message}")
+          # Graceful fallback to token-based permissions (matches JS behavior)
+          get_permissions_from_token
+        rescue StandardError => e
+          log_error("Unexpected error getting permissions from API: #{e.message}")
+          # Graceful fallback to token-based permissions
+          get_permissions_from_token
+        end
+      end
+
+      # Configurable logging that works with or without Rails
+      #
+      # @param message [String] The error message to log
+      def log_error(message)
+        if defined?(Rails) && Rails.logger
+          Rails.logger.error(message)
+        elsif @logger
+          @logger.error(message)
+        elsif respond_to?(:logger) && logger
+          logger.error(message)
+        else
+          # Fallback to STDERR if no logger available
+          $stderr.puts "[KindeSdk] ERROR: #{message}"
+        end
+      end
+
+      def log_warning(message)
+        if defined?(Rails) && Rails.logger
+          Rails.logger.warn(message)
+        elsif @logger
+          @logger.warn(message)
+        elsif respond_to?(:logger) && logger
+          logger.warn(message)
+        else
+          $stderr.puts "[KindeSdk] WARNING: #{message}"
+        end
       end
     end
   end

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