api_keys 0.2.1 → 0.3.0

data/lib/api_keys/models/api_key.rb

@@ -22,6 +22,18 @@ module ApiKeys
     # JSON attributes (:scopes, :metadata) are defined in the engine initializer
     # using ActiveSupport.on_load(:active_record) to ensure DB connection is ready.
 
+    # Override scopes setter to auto-clean blank values.
+    # This handles the common case where form checkboxes submit empty strings.
+    # Works for both create and update operations.
+    def scopes=(value)
+      cleaned = if value.is_a?(Array)
+                  value.reject { |s| s.blank? }
+                else
+                  value
+                end
+      super(cleaned)
+    end
+
     # == Validations ==
     validates :token_digest, presence: true, uniqueness: { case_sensitive: true }
     validates :prefix, presence: true
@@ -40,6 +52,8 @@ module ApiKeys
 
     # TODO: Add validation for expires_at > Time.current if present
     validate :expiration_date_cannot_be_in_the_past, if: :expires_at?
+    validate :within_key_type_limit, on: :create, if: -> { key_type.present? && owner.present? }
+    validate :non_revocable_keys_cannot_expire, if: -> { key_type.present? && expires_at.present? }
 
     # TODO: Add validation for scope string format
     # TODO: Add validation for prefix format (e.g., must end with _)
@@ -56,11 +70,53 @@ module ApiKeys
     scope :inactive, -> { revoked.or(expired) }
     scope :for_prefix, ->(prefix) { where(prefix: prefix) }
     scope :for_owner, ->(owner) { where(owner: owner) }
-    # TODO: Add more scopes as needed (e.g., for_owner)
+    scope :for_key_type, ->(key_type) { where(key_type: key_type.to_s) }
+    scope :for_environment, ->(environment) { where(environment: environment.to_s) }
+
+    # Convenience scopes for key types
+    # .publishable returns only keys with key_type: "publishable"
+    # .secret returns keys that are NOT publishable (includes legacy keys with nil/blank key_type)
+    scope :publishable, -> { where(key_type: "publishable") }
+    scope :secret, -> { where.not(key_type: "publishable") }
+
+    # === Usage Analytics Scopes ===
+    # These scopes help admin dashboards analyze API key usage patterns.
+    # Useful for identifying unused keys, high-traffic keys, and stale keys that may need cleanup.
+
+    # Keys that have never been used (last_used_at is nil)
+    scope :never_used, -> { where(last_used_at: nil) }
+
+    # Keys that have been used at least once
+    scope :used, -> { where.not(last_used_at: nil) }
+
+    # Order by usage count (highest first) - useful for finding most active keys
+    scope :by_requests, -> { order(requests_count: :desc) }
+
+    # Order by last used time (most recent first, nulls last)
+    # Uses NULLS LAST for PostgreSQL compatibility; SQLite sorts nulls last by default with DESC
+    scope :by_last_used, -> { order(Arel.sql("CASE WHEN last_used_at IS NULL THEN 1 ELSE 0 END, last_used_at DESC")) }
+
+    # Active keys that haven't been used within the specified period.
+    # Useful for identifying keys that may have been abandoned or forgotten.
+    # Excludes revoked/expired keys since those are already inactive.
+    # @param period [ActiveSupport::Duration] The inactivity threshold (default: 30 days)
+    scope :stale, ->(period = 30.days) {
+      active.where("last_used_at < :threshold OR last_used_at IS NULL", threshold: period.ago)
+    }
+
+    # Aliases for common admin dashboard naming conventions
+    class << self
+      alias_method :most_used, :by_requests
+      alias_method :recently_used, :by_last_used
+    end
+
+    # Convenience scope for 30-day stale keys (common admin filter)
+    scope :inactive_for_30_days, -> { stale(30.days) }
 
     # == Instance Methods ==
 
     def revoke!
+      raise ApiKeys::Errors::KeyNotRevocableError unless revocable?
       update!(revoked_at: Time.current)
     end
 
@@ -76,14 +132,91 @@ module ApiKeys
       !revoked? && !expired?
     end
 
+    # Returns true if this key can be revoked/destroyed
+    # Keys without a key_type (legacy) are always revocable
+    # Keys with a key_type check the configuration
+    def revocable?
+      return true if key_type.blank?
+      config = key_type_config
+      return true if config.nil?
+      config.fetch(:revocable, true)
+    end
+
+    # Returns the configuration hash for this key's type
+    def key_type_config
+      return nil if key_type.blank?
+      ApiKeys.configuration.key_types&.dig(key_type.to_sym)
+    end
+
+    # Returns the configuration hash for this key's environment
+    def environment_config
+      return nil if environment.blank?
+      ApiKeys.configuration.environments&.dig(environment.to_sym)
+    end
+
+    # Returns true if this key type is configured as public AND non-revocable.
+    # Only these keys have their plaintext token stored in metadata for later viewing.
+    # This is used for publishable keys that are designed to be embedded in distributed apps.
+    def public_key_type?
+      return false if key_type.blank?
+      config = key_type_config
+      return false if config.nil?
+      config[:public] == true && config[:revocable] == false
+    end
+
+    # Returns the stored plaintext token for public, non-revocable keys.
+    # Returns nil for all other key types (the token is only available at creation time).
+    # @return [String, nil] The full plaintext token, or nil if not stored
+    def viewable_token
+      return nil unless public_key_type?
+      metadata&.dig("token")
+    end
+
+    # Override destroy to prevent destroying non-revocable keys
+    def destroy
+      raise ApiKeys::Errors::KeyNotRevocableError unless revocable?
+      super
+    end
+
+    def destroy!
+      raise ApiKeys::Errors::KeyNotRevocableError unless revocable?
+      super
+    end
+
     # Basic scope check. Assumes scopes are stored as an array of strings.
-    # Returns true if the key has no specific scopes (allowing all) or includes the required scope.
+    #
+    # Behavior depends on whether key_types mode is enabled:
+    # - Simple mode (no key_types): blank scopes means "unrestricted" (all scopes allowed).
+    #   This preserves backwards compatibility for apps that don't use scopes at all.
+    # - Key types mode: blank scopes means "no permissions". When you've configured
+    #   key types with permission ceilings, an empty scope list should deny access,
+    #   not silently bypass the entire permission system.
     def allows_scope?(required_scope)
-      # Type casting for scopes/metadata happens via the attribute definition in the engine.
-      # Ensure the attribute is loaded/defined before using it.
-      # Check if the attribute method exists before calling .blank? or .include?
       return true unless respond_to?(:scopes) # Guard clause if loaded before attribute definition
-      scopes.blank? || scopes.include?(required_scope.to_s)
+
+      if scopes.blank?
+        # In key_types mode, blank scopes = no access (deny by default)
+        # In simple mode, blank scopes = unrestricted (allow by default)
+        return !ApiKeys.configuration.key_types.present?
+      end
+
+      scopes.include?(required_scope.to_s)
+    end
+
+    # Alias for scopes - provides a more user-friendly API that matches
+    # the configuration DSL where key types use `permissions` for scope ceiling.
+    # Note: We use a method instead of alias_method because `scopes` is defined
+    # dynamically via the `attribute` API in the engine initializer.
+    # @return [Array<String>] The permissions (scopes) assigned to this key
+    def permissions
+      scopes
+    end
+
+    # Check if this key has a specific permission (alias for allows_scope?)
+    # @param required_permission [String, Symbol] The permission to check
+    # @return [Boolean] true if the key has this permission or has no restrictions
+    def allows_permission?(required_permission)
+      allows_scope?(required_permission)
     end
 
     # Provides a masked version of the token for display (e.g., ak_live_••••rj4p)
@@ -108,25 +241,49 @@ module ApiKeys
     def set_defaults
       # NOTE: Defaults for scopes/metadata handled by `attribute` definitions in engine initializer.
 
-      # Determine the prefix: owner-specific setting > global config
-      # Note: `owner` might not be set yet if called outside normal AR flow.
-      owner_prefix_config = nil
-      if owner.present? && owner.class.respond_to?(:api_keys_settings)
-        owner_prefix_config = owner.class.api_keys_settings[:token_prefix]
-      end
+      # If key_types feature is enabled (non-empty key_types config), use type+env prefix
+      if key_types_feature_enabled? && key_type.present?
+        self.prefix ||= build_typed_prefix
+      else
+        # Legacy behavior: use owner-specific or global config prefix
+        owner_prefix_config = nil
+        if owner.present? && owner.class.respond_to?(:api_keys_settings)
+          owner_prefix_config = owner.class.api_keys_settings[:token_prefix]
+        end
 
-      # Use owner setting if present, otherwise fall back to global config
-      prefix_config = owner_prefix_config || ApiKeys.configuration.token_prefix
+        # Use owner setting if present, otherwise fall back to global config
+        prefix_config = owner_prefix_config || ApiKeys.configuration.token_prefix
 
-      # Evaluate the prefix config (it might be a Proc)
-      # Ensure `self.prefix` is only set if it's not already present.
-      self.prefix ||= prefix_config.is_a?(Proc) ? prefix_config.call : prefix_config
+        # Evaluate the prefix config (it might be a Proc)
+        self.prefix ||= prefix_config.is_a?(Proc) ? prefix_config.call : prefix_config
+      end
 
       # Removed default scopes logic here. It's correctly handled in the
       # HasApiKeys#create_api_key! helper method, which is the intended
       # way to create keys with proper default scope application.
     end
 
+    # Build prefix from key_type and environment configuration
+    # e.g., publishable + test → "pk_test_"
+    def build_typed_prefix
+      type_config = key_type_config
+      env_config = environment_config
+
+      type_prefix = type_config&.dig(:prefix) || key_type.to_s[0..1]
+      env_segment = env_config&.dig(:prefix_segment)
+
+      if env_segment.present?
+        "#{type_prefix}_#{env_segment}_"
+      else
+        "#{type_prefix}_"
+      end
+    end
+
+    # Check if key types feature is enabled
+    def key_types_feature_enabled?
+      ApiKeys.configuration.key_types.present? && ApiKeys.configuration.key_types.any?
+    end
+
     # Generates the secure token, hashes it, and sets relevant attributes.
     # Called before validation on create.
     def generate_token_and_digest
@@ -160,6 +317,14 @@ module ApiKeys
       if ApiKeys.configuration.expire_after.present? && self.expires_at.nil?
         self.expires_at = ApiKeys.configuration.expire_after.from_now
       end
+
+      # Store plaintext token in metadata for public, non-revocable keys.
+      # This allows users to view the token again in the dashboard.
+      # SECURITY: Only do this for keys explicitly configured as public: true
+      # AND revocable: false (e.g., publishable keys for distributed apps).
+      if public_key_type?
+        self.metadata = (self.metadata || {}).merge("token" => @token)
+      end
     end
 
     # == Validation Helpers ==
@@ -205,5 +370,52 @@ module ApiKeys
       errors.add(:expires_at, "can't be in the past") if expires_at.present? && expires_at < Time.current
     end
 
+    # Non-revocable keys cannot have expiration dates.
+    # If a key expires but cannot be revoked/deleted, the user would be stuck
+    # with a useless expired key they can't remove.
+    def non_revocable_keys_cannot_expire
+      return unless key_type.present? && expires_at.present?
+
+      config = key_type_config
+      return unless config # No config = allow (legacy behavior)
+
+      # If this key type is non-revocable, prevent setting expiration
+      if config[:revocable] == false
+        errors.add(:expires_at, "cannot be set on non-revocable keys (#{key_type} keys cannot be revoked or deleted)")
+      end
+    end
+
+    # Check if creating this key would exceed the limit for this key type/environment
+    # Uses row-level locking to prevent race conditions when multiple requests
+    # try to create keys concurrently.
+    def within_key_type_limit
+      return unless key_types_feature_enabled?
+
+      config = key_type_config
+      return unless config # No config = no limit
+
+      limit = config[:limit]
+      return unless limit # nil limit = unlimited
+
+      # Use pessimistic locking to prevent race conditions.
+      # Lock the owner's existing keys of this type/environment while counting.
+      # This ensures atomic check-then-create semantics.
+      #
+      # Note: We use .ids.size instead of .count because PostgreSQL doesn't allow
+      # FOR UPDATE with aggregate functions (COUNT). By selecting IDs with the
+      # lock and counting in Ruby, we achieve the same race condition protection.
+      existing_count = owner.api_keys
+                            .active
+                            .where(key_type: key_type.to_s)
+                            .where(environment: environment.to_s)
+                            .lock(true)
+                            .ids
+                            .size
+
+      if existing_count >= limit
+        errors.add(:base, "Maximum number of #{key_type} keys (#{limit}) reached for #{environment} environment")
+      end
+    end
+
   end
 end

data/lib/api_keys/models/concerns/has_api_keys.rb

@@ -95,30 +95,135 @@ module ApiKeys
         # --- Instance Methods ---
         # Methods included in the owner model (e.g., User).
 
+        # Returns the available scopes for API keys on this owner.
+        # Uses owner-specific settings if defined, otherwise falls back to global config.
+        # Useful for populating scope checkboxes in forms.
+        #
+        # @return [Array<String>] The available scopes
+        def available_api_key_scopes
+          owner_settings = self.class.api_keys_settings
+          owner_settings&.[](:default_scopes) || ApiKeys.configuration.default_scopes || []
+        end
+
+        # Checks if this owner can create an API key of the given type.
+        # Returns false if the limit for this key type/environment is reached.
+        # Useful for conditional UI (e.g., hiding "Create" button when at limit).
+        #
+        # Note: This is a best-effort check for UI purposes without locking.
+        # Concurrent requests could see stale data. The actual limit is enforced
+        # with pessimistic locking in create_api_key!, so this is safe to use
+        # for UI decisions (worst case: button shown but creation fails validation).
+        #
+        # @param key_type [Symbol, nil] The key type to check (e.g., :publishable, :secret)
+        # @param environment [Symbol, nil] The environment to check (defaults to current_environment)
+        # @return [Boolean] true if the owner can create another key of this type
+        #
+        # @example
+        #   if current_org.can_create_api_key?(key_type: :publishable)
+        #     # Show "Create Publishable Key" button
+        #   end
+        #
+        def can_create_api_key?(key_type: nil, environment: nil)
+          config = ApiKeys.configuration
+
+          # If no key_type specified, check global quota only
+          return within_global_quota? if key_type.nil?
+
+          # Resolve environment
+          resolved_environment = resolve_environment(environment, key_type, config)
+
+          # Get type-specific limit
+          type_config = config.key_types&.dig(key_type.to_sym)
+          return within_global_quota? unless type_config
+
+          limit = type_config[:limit]
+          return within_global_quota? unless limit
+
+          # Count existing keys of this type/environment
+          existing_count = api_keys
+                            .active
+                            .where(key_type: key_type.to_s)
+                            .where(environment: resolved_environment.to_s)
+                            .count
+
+          existing_count < limit && within_global_quota?
+        end
+
         # Creates a new API key for this owner instance and returns the ApiKey instance.
         # Raises ActiveRecord::RecordInvalid if creation fails.
         #
         # @param name [String] The name for the new API key (required).
         # @param scopes [Array<String>, nil] Scopes for the key. Defaults to owner/global settings.
+        #   When key_type is specified, scopes are filtered to only include those allowed
+        #   by the key type's permissions ceiling. Blank values are automatically removed.
         # @param expires_at [Time, nil] Optional expiration timestamp.
+        # @param expires_at_preset [String, nil] Convenience param: "7_days", "30_days", "no_expiration", etc.
+        #   If provided, this is parsed into expires_at. Takes precedence over expires_at if both given.
         # @param metadata [Hash, nil] Optional metadata hash.
+        # @param key_type [Symbol, nil] The key type (e.g., :publishable, :secret).
+        #   Must be defined in ApiKeys.configuration.key_types if provided.
+        # @param environment [Symbol, nil] The environment (e.g., :test, :live).
+        #   Defaults to current_environment if key_types feature is enabled.
         # @return [ApiKeys::ApiKey] The newly created ApiKey instance. The plaintext token
         #                           is available via the `#token` attribute on this instance
         #                           *only until it's reloaded*.
-        def create_api_key!(name: nil, scopes: nil, expires_at: nil, metadata: nil)
+        def create_api_key!(name: nil, scopes: nil, expires_at: nil, expires_at_preset: nil, metadata: nil, key_type: nil, environment: nil)
+          config = ApiKeys.configuration
+
+          # Parse expires_at_preset if provided (takes precedence over expires_at)
+          if expires_at_preset.present?
+            expires_at = ApiKeys::Helpers::ExpirationOptions.parse(expires_at_preset)
+          end
+
+          # Auto-clean scopes: remove blank values from arrays (common when using form checkboxes)
+          if scopes.is_a?(Array)
+            scopes = scopes.reject { |s| s.blank? }
+          end
+
+          # Check for missing columns if key_types feature is enabled
+          if key_types_feature_enabled?(config)
+            check_required_columns!
+          end
+
+          # Use default_key_type if not specified and key_types feature is enabled
+          resolved_key_type = key_type
+          if resolved_key_type.nil? && key_types_feature_enabled?(config) && config.default_key_type.present?
+            resolved_key_type = config.default_key_type
+          end
+
+          # Validate key_type if provided and key_types feature is enabled
+          if resolved_key_type.present?
+            validate_key_type!(resolved_key_type, config)
+          end
+
+          # Determine environment: use provided, or default from config
+          resolved_environment = resolve_environment(environment, resolved_key_type, config)
+
+          # Validate environment if key_types feature is enabled
+          if resolved_environment.present? && key_types_feature_enabled?(config)
+            validate_environment!(resolved_environment, config)
+          end
+
           # Fetch default scopes from this owner class's settings, falling back to global config.
           owner_settings = self.class.api_keys_settings
-          default_scopes = owner_settings&.[](:default_scopes) || ApiKeys.configuration.default_scopes || []
+          default_scopes = owner_settings&.[](:default_scopes) || config.default_scopes || []
 
           # Use provided scopes if given, otherwise use the calculated defaults.
           key_scopes = scopes.nil? ? default_scopes : Array(scopes)
 
+          # Filter scopes based on key type permissions ceiling
+          if resolved_key_type.present?
+            key_scopes = filter_scopes_by_permissions(key_scopes, resolved_key_type, config)
+          end
+
           # Create the key using the association, letting AR handle owner_id/type.
           api_key = self.api_keys.create!(
             name: name,
             scopes: key_scopes,
             expires_at: expires_at,
-            metadata: metadata || {} # Ensure metadata is at least an empty hash
+            metadata: metadata || {}, # Ensure metadata is at least an empty hash
+            key_type: resolved_key_type&.to_s,
+            environment: resolved_environment&.to_s
             # prefix, token_digest, digest_algorithm are set by ApiKey callbacks
           )
 
@@ -127,6 +232,81 @@ module ApiKeys
           api_key
         end
 
+        private
+
+        def within_global_quota?
+          owner_settings = self.class.api_keys_settings
+          limit = owner_settings&.[](:max_keys) || ApiKeys.configuration.default_max_keys_per_owner
+          return true unless limit
+
+          api_keys.active.count < limit
+        end
+
+        def key_types_feature_enabled?(config)
+          config.key_types.present? && config.key_types.any?
+        end
+
+        def validate_key_type!(key_type, config)
+          return unless key_types_feature_enabled?(config)
+
+          valid_types = config.key_types.keys.map(&:to_sym)
+          unless valid_types.include?(key_type.to_sym)
+            raise ArgumentError, "Invalid key type '#{key_type}'. Valid types: #{valid_types.join(', ')}"
+          end
+        end
+
+        def validate_environment!(environment, config)
+          return unless config.environments.present? && config.environments.any?
+
+          valid_environments = config.environments.keys.map(&:to_sym)
+          unless valid_environments.include?(environment.to_sym)
+            raise ArgumentError, "Invalid environment '#{environment}'. Valid environments: #{valid_environments.join(', ')}"
+          end
+        end
+
+        def resolve_environment(provided_environment, key_type, config)
+          # If explicitly provided, use that
+          return provided_environment if provided_environment.present?
+
+          # If key_types feature is enabled, use current_environment
+          if key_types_feature_enabled?(config) && key_type.present?
+            env_lambda = config.current_environment
+            return env_lambda.respond_to?(:call) ? env_lambda.call : env_lambda
+          end
+
+          nil
+        end
+
+        def filter_scopes_by_permissions(scopes, key_type, config)
+          return scopes unless key_types_feature_enabled?(config)
+
+          type_config = config.key_types[key_type.to_sym]
+          return scopes unless type_config
+
+          permissions = type_config[:permissions]
+
+          # :all means no filtering
+          return scopes if permissions == :all
+
+          # Filter to only include scopes that are within the permissions ceiling
+          return [] if permissions.nil? || permissions.empty?
+
+          scopes.select { |scope| permissions.include?(scope.to_s) }
+        end
+
+        # Check that required columns exist for key_types feature
+        # Raises MigrationRequiredError if columns are missing
+        def check_required_columns!
+          required_columns = %w[key_type environment]
+          existing_columns = ApiKeys::ApiKey.column_names
+
+          missing_columns = required_columns - existing_columns
+
+          if missing_columns.any?
+            raise ApiKeys::Errors::MigrationRequiredError.new(missing_columns: missing_columns)
+          end
+        end
+
         # Example: Check if the owner has reached their API key limit.
         # def reached_api_key_limit?
         #   limit = self.class.api_keys_settings[:max_keys]

data/lib/api_keys/services/authenticator.rb

@@ -63,8 +63,15 @@ module ApiKeys
 
         result = if api_key&.active?
                    log_debug "[ApiKeys Auth] Verification successful. Key ID: #{api_key.id}"
-                   # TODO: Optionally update last_used_at and requests_count
-                   Result.success(api_key)
+
+                   # Check environment isolation if enabled
+                   env_check_result = check_environment_isolation(api_key, config)
+                   if env_check_result
+                     env_check_result  # Return failure result
+                   else
+                     # TODO: Optionally update last_used_at and requests_count
+                     Result.success(api_key)
+                   end
                  elsif api_key&.revoked?
                    log_debug "[ApiKeys Auth] Verification failed: Key revoked. Key ID: #{api_key.id}"
                    Result.failure(error_code: :revoked_key, message: "API key has been revoked")
@@ -246,6 +253,42 @@ module ApiKeys
         defined?(Rails) ? Rails.cache : nil
       end
 
+      # Check if the API key's environment matches the current environment
+      # Returns a failure Result if there's a mismatch and strict isolation is enabled
+      # Returns nil if the check passes or is not applicable
+      def self.check_environment_isolation(api_key, config)
+        return nil unless config.strict_environment_isolation
+
+        # Skip check if key doesn't have an environment (legacy keys)
+        key_env = api_key.environment
+        return nil if key_env.blank?
+
+        # Get current environment
+        current_env_config = config.current_environment
+        current_env = current_env_config.respond_to?(:call) ? current_env_config.call : current_env_config
+
+        # Normalize to string first, then check if blank
+        # This ensures consistent string comparison and prevents edge cases with empty strings
+        current_env = current_env.to_s
+        key_env = key_env.to_s
+
+        # Skip isolation check if current environment is blank (not properly configured)
+        if current_env.blank?
+          log_debug "[ApiKeys Auth] Current environment is blank, skipping environment isolation check"
+          return nil
+        end
+
+        if current_env != key_env
+          log_debug "[ApiKeys Auth] Environment mismatch: Key environment '#{key_env}' does not match current environment '#{current_env}'"
+          return Result.failure(
+            error_code: :environment_mismatch,
+            message: "API key environment (#{key_env}) does not match current environment (#{current_env})"
+          )
+        end
+
+        nil # Check passed
+      end
+
       # NOTE: Removing the incorrect private `find_key_by_token` method.
       # def find_key_by_token(token)
       #   ...

data/lib/api_keys/services/digestor.rb

@@ -55,12 +55,16 @@ module ApiKeys
           comparison_proc.call(stored_digest, Digest::SHA256.hexdigest(token))
         else
           # Strategy mismatch or unsupported strategy should fail comparison safely
-          Rails.logger.error "[ApiKeys] Digestor comparison failed: Unsupported hash strategy '#{strategy}' for digest check." if defined?(Rails.logger)
+          if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+            Rails.logger.error "[ApiKeys] Digestor comparison failed: Unsupported hash strategy '#{strategy}' for digest check."
+          end
           false
         end
       rescue ArgumentError => e
         # Catch potential errors from Digest or comparison proc
-        Rails.logger.error "[ApiKeys] Digestor comparison error: #{e.message}" if defined?(Rails.logger)
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error "[ApiKeys] Digestor comparison error: #{e.message}"
+        end
         false
       end
     end

data/lib/api_keys/tenant_resolution.rb

@@ -33,7 +33,9 @@ module ApiKeys
       @current_api_tenant = resolver&.call(current_api_key)
     rescue StandardError => e
       # Log error but don't break the request if resolver fails
-      Rails.logger.error "[ApiKeys] Tenant resolution failed: #{e.message}" if defined?(Rails.logger)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error "[ApiKeys] Tenant resolution failed: #{e.message}"
+      end
       @current_api_tenant = nil
     end
   end

data/lib/api_keys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiKeys
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/api_keys.rb

@@ -53,12 +53,24 @@ end
 
 require "api_keys/version"
 require "api_keys/configuration" # Defines the ApiKeys::Configuration class
+require "api_keys/errors" # Error classes for key types feature
 
 # Files that might depend on ApiKeys.configuration being available
 require "api_keys/controller" # This can lead to loading jobs, etc.
 require "api_keys/models/concerns/has_api_keys"
 require "api_keys/models/api_key"
 
+# Helpers for integrators building custom UIs
+require "api_keys/helpers/token_session"
+require "api_keys/helpers/expiration_options"
+require "api_keys/helpers/view_helpers"
+require "api_keys/form_builder_extensions"
+
+# Top-level aliases for cleaner API (ApiKeys::TokenSession instead of ApiKeys::Helpers::TokenSession)
+ApiKeys::TokenSession = ApiKeys::Helpers::TokenSession
+ApiKeys::ExpirationOptions = ApiKeys::Helpers::ExpirationOptions
+ApiKeys::ViewHelpers = ApiKeys::Helpers::ViewHelpers
+
 # Rails integration (Engine)
 # The Engine might also access ApiKeys.configuration during its initialization.
 require "api_keys/engine" if defined?(Rails)