kinde_sdk 1.6.6 → 1.7.0

data/lib/kinde_sdk/client/feature_flags.rb

@@ -1,7 +1,168 @@
 module KindeSdk
   class Client
     module FeatureFlags
-      def get_flag(name, opts = {}, flag_type = nil)
+      # Get all feature flags for the authenticated user
+      # Matches the JavaScript SDK API: getFlags(options?)
+      #
+      # @param options [Hash] Options for retrieving feature flags
+      # @option options [Boolean] :force_api (false) If true, calls the API to get fresh flags,
+      #   otherwise extracts from token claims. Useful for ensuring latest flags 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 [Array] Array of flag objects with key, value, and type
+      # @example
+      #   # Soft check (from token)
+      #   client.get_flags
+      #   # => [{ key: "feature_a", value: true, type: "boolean" }]
+      #
+      #   # Hard check (from API)
+      #   client.get_flags(force_api: true)
+      #   # => [{ key: "feature_a", value: true, type: "boolean" }]
+      def get_flags(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 flags
+          get_flags_from_api
+        else
+          # Soft check - extract from token claims
+          get_flags_from_token(token_type)
+        end
+      end
+
+      # Get a specific feature flag
+      # Supports both new API-style calls and legacy 3-parameter calls
+      #
+      # @param name [String] The flag name/key to retrieve
+      # @param options_or_opts [Hash] Options for retrieving flags OR legacy opts hash
+      # @param flag_type [String, nil] Legacy flag type parameter (for 3-param calls)
+      # @return [Hash, nil] Flag object or nil if not found
+      def get_flag(name, options_or_opts = {}, flag_type = nil)
+        # Handle legacy 3-parameter signature: get_flag(name, opts, flag_type)
+        if flag_type || (options_or_opts.is_a?(Hash) && options_or_opts.key?(:default_value) && !options_or_opts.key?(:force_api))
+          return get_flag_legacy(name, options_or_opts, flag_type)
+        end
+
+        get_flag_new_api(name, options_or_opts)
+      end
+
+      # Check if user has specific feature flags
+      #
+      # @param flag_conditions [Array] Array of flag keys or flag condition objects
+      # @param options [Hash] Options for retrieving flags (same as get_flags)
+      # @return [Boolean] True if user has all specified flags, false otherwise
+      def has_feature_flags?(flag_conditions, options = {})
+        return true if flag_conditions.nil? || flag_conditions.empty?
+        
+        flags = get_flags(options)
+        flag_conditions_array = Array(flag_conditions)
+        
+        flag_conditions_array.all? { |condition| check_flag_condition(condition, flags) }
+      end
+
+      # Legacy methods for backward compatibility
+      def get_boolean_flag(name, default_value = nil)
+        flag_getter_wrapper(name, "b", default_value)
+      end
+
+      def get_string_flag(name, default_value = nil)
+        flag_getter_wrapper(name, "s", default_value)
+      end
+
+      def get_integer_flag(name, default_value = nil)
+        flag_getter_wrapper(name, "i", default_value)
+      end
+
+      # PHP SDK compatible alias
+      def getFlags
+        # Use client's force_api setting, default to true for PHP SDK compatibility
+        force_api_setting = @force_api.nil? ? true : @force_api
+        get_flags(force_api: force_api_setting)
+      end
+
+      # JavaScript SDK compatible alias
+      alias_method :hasFeatureFlags, :has_feature_flags?
+
+      private
+
+      # New API-style get_flag implementation
+      # Handles the modern get_flag(name, options) signature
+      #
+      # @param name [String] The flag name/key to retrieve
+      # @param options [Hash] Options for retrieving flags
+      # @return [Hash, nil] Flag object or nil if not found
+      def get_flag_new_api(name, options)
+        flags = get_flags(options)
+        flag = find_flag_by_key(flags, name)
+        
+        return nil unless flag
+        
+        {
+          code: get_flag_key(flag),
+          type: get_flag_type(flag),
+          value: get_flag_value(flag),
+          is_default: false
+        }
+      end
+
+      # Check a single flag condition against available flags
+      #
+      # @param condition [Hash, String] Flag condition to check
+      # @param flags [Array] Available flags to check against
+      # @return [Boolean] True if condition is met, false otherwise
+      def check_flag_condition(condition, flags)
+        if condition.is_a?(Hash) && condition.key?(:flag) && condition.key?(:value)
+          # Custom condition with specific value
+          flag = find_flag_by_key(flags, condition[:flag])
+          flag && get_flag_value(flag) == condition[:value]
+        else
+          # Simple existence check
+          !!find_flag_by_key(flags, condition.to_s)
+        end
+      end
+
+      # Find a flag by its key in the flags array
+      #
+      # @param flags [Array] Array of flag objects
+      # @param key [String] The key to search for
+      # @return [Hash, nil] Flag object if found, nil otherwise
+      def find_flag_by_key(flags, key)
+        flags.find { |f| get_flag_key(f) == key.to_s }
+      end
+
+      # Extract the key from a flag object (handles both symbol and string keys)
+      #
+      # @param flag [Hash] Flag object
+      # @return [String] The flag key
+      def get_flag_key(flag)
+        flag[:key] || flag['key']
+      end
+
+      # Extract the value from a flag object (handles both symbol and string keys)
+      #
+      # @param flag [Hash] Flag object
+      # @return [Object] The flag value
+      def get_flag_value(flag)
+        flag[:value] || flag['value']
+      end
+
+      # Extract the type from a flag object (handles both symbol and string keys)
+      #
+      # @param flag [Hash] Flag object
+      # @return [String] The flag type
+      def get_flag_type(flag)
+        flag[:type] || flag['type']
+      end
+
+      # Legacy get_flag implementation for backward compatibility
+      # Handles the 3-parameter signature: get_flag(name, opts, flag_type)
+      def get_flag_legacy(name, opts = {}, flag_type = nil)
         res = get_claim("feature_flags")&.dig(:value, name)
         return try_default_flag(flag_type, name, opts) unless res
 
@@ -20,22 +181,84 @@ module KindeSdk
         }
       end
 
-      def get_boolean_flag(name, default_value = nil)
-        flag_getter_wrapper(name, "b", default_value)
-      end
+      # Get feature flags from token claims (soft check)
+      # Matches JavaScript logic: token.feature_flags || token["x-hasura-feature-flags"] || null
+      #
+      # @param token_type [Symbol] The token type to use
+      # @return [Array] Array of flag objects
+      def get_flags_from_token(token_type = :access_token)
+        # First try standard feature_flags claim
+        flags = get_claim("feature_flags", token_type)&.dig(:value)
+        
+        # Fallback to Hasura-specific flags (matches JS SDK)
+        if flags.nil? || flags.empty?
+          flags = get_claim("x-hasura-feature-flags", token_type)&.dig(:value)
+        end
+        
+        return [] if flags.nil? || flags.empty?
 
-      def get_string_flag(name, default_value = nil)
-        flag_getter_wrapper(name, "s", default_value)
+        # Convert from token format to consistent array format
+        if flags.is_a?(Hash)
+          flags.map do |key, value|
+            {
+              key: key.to_s,
+              value: value.is_a?(Hash) ? value['v'] : value,
+              type: value.is_a?(Hash) ? map_flag_type(value['t']) : 'string'
+            }
+          end
+        else
+          []
+        end
       end
 
-      def get_integer_flag(name, default_value = nil)
-        flag_getter_wrapper(name, "i", default_value)
+      # Get feature flags from API (hard check)
+      # Matches JavaScript API endpoint and data extraction exactly
+      #
+      # @return [Array] Array of flag objects
+      def get_flags_from_api
+        unless token_store.bearer_token
+          return []
+        end
+
+        begin
+          # Use the same pagination pattern as getAllEntitlements
+          all_flags = paginate_all_results('feature_flags') do |starting_after|
+            user_feature_flags(page_size: 100, starting_after: starting_after)
+          end
+
+          # Extract flag data (matches JS: feature_flags?.map((flag) => ({ key, value, type })))
+          all_flags.map do |flag|
+            {
+              key: flag.respond_to?(:key) ? flag.key : flag['key'],
+              value: flag.respond_to?(:value) ? flag.value : flag['value'],
+              type: flag.respond_to?(:type) ? flag.type : flag['type']
+            }
+          end.compact
+        rescue KindeSdk::APIError => e
+          log_error("API Error getting feature flags: #{e.message}")
+          # Graceful fallback to token-based flags (matches JS behavior)
+          get_flags_from_token
+        rescue StandardError => e
+          log_error("Unexpected error getting feature flags from API: #{e.message}")
+          # Graceful fallback to token-based flags
+          get_flags_from_token
+        end
       end
 
-      private
+      # Map token flag type codes to full names
+      def map_flag_type(type_code)
+        case type_code
+        when "b" then "boolean"
+        when "s" then "string"
+        when "i" then "integer"
+        when "o" then "object"
+        else "string"
+        end
+      end
 
+      # Legacy helper methods
       def flag_getter_wrapper(name, type, default_value = nil)
-        v = get_flag(name, { default_value: default_value }, type)[:value]
+        v = get_flag_legacy(name, { default_value: default_value }, type)[:value]
         raise ArgumentError, "Flag #{name} value type is different from requested type" unless check_type(v, type)
 
         v
@@ -59,6 +282,19 @@ module KindeSdk
       def check_type(value, type)
         type == "s" && value.is_a?(String) || type == "b" && (value == false || value == true) || type == "i" && value.is_a?(Integer)
       end
+
+      # Configurable logging that works with or without Rails
+      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
+          $stderr.puts "[KindeSdk] ERROR: #{message}"
+        end
+      end
     end
   end
 end

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