api_keys 0.2.0 → 0.3.0

data/lib/api_keys/form_builder_extensions.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  # Opt-in form builder extensions for API key forms.
+  #
+  # These helpers reduce boilerplate while letting you control the styling.
+  # Include them in your form builder to use:
+  #
+  #   # In config/initializers/api_keys.rb:
+  #   Rails.application.config.to_prepare do
+  #     ActionView::Helpers::FormBuilder.include(ApiKeys::FormBuilderExtensions)
+  #   end
+  #
+  # @example Expiration select
+  #   <%= form.api_key_expiration_select(class: "my-select-class") %>
+  #
+  # @example Scopes checkboxes with block for custom rendering
+  #   <%= form.api_key_scopes_checkboxes(@scopes) do |scope, checked| %>
+  #     <label>
+  #       <%= check_box_tag "api_key[scopes][]", scope, checked, class: "my-checkbox" %>
+  #       <%= scope %>
+  #     </label>
+  #   <% end %>
+  #
+  module FormBuilderExtensions
+    # Renders a select field for API key expiration presets.
+    #
+    # @param options [Hash] Options passed to the select helper
+    # @param html_options [Hash] HTML attributes for the select element
+    # @return [String] HTML select element
+    #
+    # @example Basic usage
+    #   <%= form.api_key_expiration_select %>
+    #
+    # @example With Tailwind classes
+    #   <%= form.api_key_expiration_select(class: "w-full px-4 py-3 border rounded-lg") %>
+    #
+    # @example With custom default
+    #   <%= form.api_key_expiration_select(selected: "30_days") %>
+    #
+    def api_key_expiration_select(options = {}, html_options = {})
+      # expires_at_preset is a form-only param, not a model attribute
+      # So we only use the provided :selected option or default
+      selected = options.delete(:selected) || ApiKeys::ExpirationOptions.default_value
+
+      select(
+        :expires_at_preset,
+        @template.options_for_select(ApiKeys::ExpirationOptions.for_select, selected),
+        options,
+        html_options
+      )
+    end
+
+    # Renders checkboxes for API key scopes.
+    #
+    # If a block is given, yields each scope and its checked state for custom rendering.
+    # If no block is given, returns an array of checkbox data for manual iteration.
+    #
+    # @param scopes [Array<String>] Available scopes to render
+    # @param checked [Symbol, Array] Which scopes should be checked:
+    #   - :all (default for new records) - all scopes checked
+    #   - :none - no scopes checked
+    #   - Array - specific scopes to check
+    #   - nil - uses the object's current scopes
+    # @return [String, Array] HTML if block given, otherwise array of scope data
+    #
+    # @example With block (recommended for custom styling)
+    #   <%= form.api_key_scopes_checkboxes(@scopes) do |scope, checked| %>
+    #     <label class="flex items-center gap-2">
+    #       <%= check_box_tag "api_key[scopes][]", scope, checked, class: "rounded" %>
+    #       <code><%= scope %></code>
+    #     </label>
+    #   <% end %>
+    #
+    # @example Simple rendering without block
+    #   <% form.api_key_scopes_checkboxes(@scopes).each do |scope_data| %>
+    #     <%= check_box_tag "api_key[scopes][]", scope_data[:value], scope_data[:checked] %>
+    #     <%= scope_data[:value] %>
+    #   <% end %>
+    #
+    def api_key_scopes_checkboxes(scopes, checked: nil, &block)
+      # Determine which scopes should be checked
+      checked_scopes = resolve_checked_scopes(scopes, checked)
+
+      scope_data = scopes.map do |scope|
+        {
+          value: scope,
+          checked: checked_scopes.include?(scope),
+          field_name: "#{object_name}[scopes][]"
+        }
+      end
+
+      if block_given?
+        # Yield each scope for custom rendering
+        safe_buffer = ActiveSupport::SafeBuffer.new
+        scope_data.each do |data|
+          safe_buffer << @template.capture { yield(data[:value], data[:checked]) }
+        end
+        safe_buffer
+      else
+        # Return raw data for manual iteration
+        scope_data
+      end
+    end
+
+    # Returns structured data for building a token display UI.
+    # Useful when you need to build a custom token display with copy functionality.
+    #
+    # @return [Hash] Token display data with keys:
+    #   - :masked [String] The masked token (e.g., "sk_live_••••abc")
+    #   - :full [String, nil] The full token (only for viewable public keys)
+    #   - :viewable [Boolean] Whether the full token can be displayed
+    #   - :type [Symbol] The key type (:publishable, :secret, or nil)
+    #   - :environment [String, nil] The environment (e.g., "live", "test")
+    #
+    # @example
+    #   <% data = form.api_key_token_data %>
+    #   <code><%= data[:masked] %></code>
+    #   <% if data[:viewable] %>
+    #     <button data-token="<%= data[:full] %>">Copy</button>
+    #   <% end %>
+    #
+    def api_key_token_data
+      return {} unless object.respond_to?(:masked_token)
+
+      {
+        masked: object.masked_token,
+        full: object.viewable_token,
+        viewable: object.respond_to?(:public_key_type?) && object.public_key_type?,
+        type: object.key_type&.to_sym,
+        environment: object.environment
+      }
+    end
+
+    private
+
+    def resolve_checked_scopes(scopes, checked)
+      case checked
+      when :all
+        scopes.map(&:to_s)
+      when :none
+        []
+      when Array
+        checked.map(&:to_s)
+      when nil
+        # For new records, default to all checked
+        # For existing records, use the object's scopes
+        if object&.persisted?
+          (object.scopes || []).map(&:to_s)
+        else
+          scopes.map(&:to_s)
+        end
+      else
+        scopes.map(&:to_s)
+      end
+    end
+  end
+end

data/lib/api_keys/helpers/expiration_options.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  module Helpers
+    # Helper for handling API key expiration presets.
+    #
+    # Provides a consistent set of expiration options for use in forms,
+    # and parsing logic to convert preset strings to actual dates.
+    #
+    # @example In your view (form select)
+    #   <%= form.select :expires_at_preset,
+    #       ApiKeys::Helpers::ExpirationOptions.for_select %>
+    #
+    # @example In your controller
+    #   expires_at = ApiKeys::Helpers::ExpirationOptions.parse(params[:expires_at_preset])
+    #   @api_key = current_org.create_api_key!(expires_at: expires_at, ...)
+    #
+    class ExpirationOptions
+      # Default preset options with human-readable labels
+      DEFAULT_PRESETS = [
+        { label: "No Expiration", value: "no_expiration", days: nil },
+        { label: "7 days", value: "7_days", days: 7 },
+        { label: "30 days", value: "30_days", days: 30 },
+        { label: "60 days", value: "60_days", days: 60 },
+        { label: "90 days", value: "90_days", days: 90 },
+        { label: "1 year", value: "365_days", days: 365 }
+      ].freeze
+
+      class << self
+        # Returns options suitable for a Rails select helper.
+        #
+        # @param include_no_expiration [Boolean] Whether to include "No Expiration" option (default: true)
+        # @param presets [Array<Integer>, nil] Custom list of days to include (e.g., [7, 30, 90])
+        #   If nil, uses DEFAULT_PRESETS
+        # @return [Array<Array>] Array of [label, value] pairs for select helper
+        #
+        # @example Default options
+        #   ExpirationOptions.for_select
+        #   # => [["No Expiration", "no_expiration"], ["7 days", "7_days"], ...]
+        #
+        # @example Custom presets
+        #   ExpirationOptions.for_select(presets: [7, 30, 365])
+        #   # => [["No Expiration", "no_expiration"], ["7 days", "7_days"], ["30 days", "30_days"], ["1 year", "365_days"]]
+        #
+        # @example Without "No Expiration"
+        #   ExpirationOptions.for_select(include_no_expiration: false)
+        #   # => [["7 days", "7_days"], ["30 days", "30_days"], ...]
+        #
+        def for_select(include_no_expiration: true, presets: nil)
+          options = if presets
+                      build_custom_presets(presets, include_no_expiration)
+                    else
+                      filter_default_presets(include_no_expiration)
+                    end
+
+          options.map { |opt| [opt[:label], opt[:value]] }
+        end
+
+        # Parse an expiration preset string into an actual datetime.
+        #
+        # @param preset [String, nil] The preset value (e.g., "30_days", "no_expiration")
+        # @return [ActiveSupport::TimeWithZone, nil] The expiration date, or nil for no expiration
+        #
+        # @example
+        #   ExpirationOptions.parse("30_days")  # => 30.days.from_now
+        #   ExpirationOptions.parse("no_expiration")  # => nil
+        #   ExpirationOptions.parse(nil)  # => nil
+        #   ExpirationOptions.parse("invalid")  # => nil
+        #
+        def parse(preset)
+          return nil if preset.blank? || preset == "no_expiration"
+
+          # Try to extract days from the preset string (e.g., "30_days" => 30)
+          if preset =~ /\A(\d+)_days?\z/
+            days = ::Regexp.last_match(1).to_i
+            # Reasonable max: ~10 years to prevent overflow issues
+            return days.days.from_now if days.positive? && days <= 3650
+          end
+
+          # Check against known presets
+          known = DEFAULT_PRESETS.find { |p| p[:value] == preset }
+          return known[:days].days.from_now if known && known[:days]
+
+          nil
+        end
+
+        # Returns the default preset value (useful for form defaults)
+        #
+        # @return [String] The default preset value
+        def default_value
+          "no_expiration"
+        end
+
+        private
+
+        def filter_default_presets(include_no_expiration)
+          if include_no_expiration
+            DEFAULT_PRESETS
+          else
+            DEFAULT_PRESETS.reject { |p| p[:value] == "no_expiration" }
+          end
+        end
+
+        def build_custom_presets(days_list, include_no_expiration)
+          options = []
+
+          if include_no_expiration
+            options << { label: "No Expiration", value: "no_expiration", days: nil }
+          end
+
+          days_list.each do |days|
+            options << preset_for_days(days)
+          end
+
+          options
+        end
+
+        def preset_for_days(days)
+          label = case days
+                  when 1 then "1 day"
+                  when 365 then "1 year"
+                  when ->(d) { d % 365 == 0 } then "#{days / 365} years"
+                  else "#{days} days"
+                  end
+
+          { label: label, value: "#{days}_days", days: days }
+        end
+      end
+    end
+  end
+end

data/lib/api_keys/helpers/token_session.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  module Helpers
+    # Helper for managing API key tokens in the session.
+    #
+    # Secret keys can only be shown once (immediately after creation) because
+    # the plaintext token is not stored in the database. This helper provides
+    # a clean interface for the "show token once" pattern:
+    #
+    # 1. After creating a key, store the token in the session
+    # 2. On the success page, retrieve (and clear) the token
+    # 3. If the user refreshes, the token is gone
+    #
+    # @example In your controller
+    #   # After creating a key:
+    #   def create
+    #     @api_key = current_org.create_api_key!(...)
+    #     ApiKeys::Helpers::TokenSession.store(session, @api_key)
+    #     redirect_to success_path
+    #   end
+    #
+    #   # On the success page:
+    #   def success
+    #     @token = ApiKeys::Helpers::TokenSession.retrieve_once(session)
+    #     redirect_to index_path, alert: "Token already shown" unless @token
+    #   end
+    #
+    class TokenSession
+      # Default session key for storing the token
+      DEFAULT_SESSION_KEY = :api_keys_new_token
+
+      class << self
+        # Store an API key's token in the session for later retrieval.
+        #
+        # @param session [ActionDispatch::Request::Session] The Rails session
+        # @param api_key [ApiKeys::ApiKey] The newly created API key
+        # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
+        # @return [String] The token that was stored
+        def store(session, api_key, key: DEFAULT_SESSION_KEY)
+          token = api_key.respond_to?(:token) ? api_key.token : api_key.to_s
+          session[key] = token
+          token
+        end
+
+        # Retrieve and clear the token from the session.
+        # Returns nil if no token is stored (e.g., page was refreshed).
+        #
+        # @param session [ActionDispatch::Request::Session] The Rails session
+        # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
+        # @return [String, nil] The token, or nil if not present
+        def retrieve_once(session, key: DEFAULT_SESSION_KEY)
+          session.delete(key)
+        end
+
+        # Check if a token is available in the session without removing it.
+        # Useful for conditional rendering.
+        #
+        # @param session [ActionDispatch::Request::Session] The Rails session
+        # @param key [Symbol] Optional custom session key (default: :api_keys_new_token)
+        # @return [Boolean] true if a token is stored
+        def available?(session, key: DEFAULT_SESSION_KEY)
+          session[key].present?
+        end
+      end
+    end
+  end
+end

data/lib/api_keys/helpers/view_helpers.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module ApiKeys
+  module Helpers
+    # View helpers for displaying API key information.
+    #
+    # These helpers provide formatted data without HTML opinions,
+    # allowing integrators to build their own UI while using
+    # consistent data formatting.
+    #
+    # @example Include in your ApplicationHelper
+    #   module ApplicationHelper
+    #     include ApiKeys::Helpers::ViewHelpers
+    #   end
+    #
+    # @example Or include in a specific controller
+    #   class Settings::ApiKeysController < ApplicationController
+    #     helper ApiKeys::Helpers::ViewHelpers
+    #   end
+    #
+    module ViewHelpers
+      # Returns the status of an API key as a symbol.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [Symbol] :active, :expired, or :revoked
+      #
+      # @example
+      #   api_key_status(@key) # => :active
+      #
+      def api_key_status(api_key)
+        return :revoked if api_key.revoked?
+        return :expired if api_key.expired?
+
+        :active
+      end
+
+      # Returns a human-readable status label for an API key.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [String] "Active", "Expired", or "Revoked"
+      #
+      # @example
+      #   api_key_status_label(@key) # => "Active"
+      #
+      def api_key_status_label(api_key)
+        case api_key_status(api_key)
+        when :active then "Active"
+        when :expired then "Expired"
+        when :revoked then "Revoked"
+        end
+      end
+
+      # Returns the environment label for an API key.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [String] "Test", "Live", or "Default" (if no environment set)
+      #
+      # @example
+      #   api_key_environment_label(@key) # => "Live"
+      #
+      def api_key_environment_label(api_key)
+        return "Default" if api_key.environment.blank?
+
+        api_key.environment.to_s.capitalize
+      end
+
+      # Returns the key type label for an API key.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [String] "Publishable", "Secret", or the key_type capitalized
+      #
+      # @example
+      #   api_key_type_label(@key) # => "Secret"
+      #
+      def api_key_type_label(api_key)
+        return "Secret" if api_key.key_type.blank?
+
+        case api_key.key_type.to_s
+        when "publishable" then "Publishable"
+        when "secret" then "Secret"
+        else api_key.key_type.to_s.capitalize
+        end
+      end
+
+      # Returns whether the key is a publishable (public) key type.
+      # Useful for conditional rendering (e.g., showing/hiding copy button).
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [Boolean] true if the key is publishable
+      #
+      # @example
+      #   <% if api_key_publishable?(@key) %>
+      #     <%= button_tag "Copy", data: { token: @key.viewable_token } %>
+      #   <% end %>
+      #
+      def api_key_publishable?(api_key)
+        api_key.key_type.to_s == "publishable"
+      end
+
+      # Returns whether the key is a secret key type.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [Boolean] true if the key is secret (or legacy with no type)
+      #
+      def api_key_secret?(api_key)
+        api_key.key_type.blank? || api_key.key_type.to_s == "secret"
+      end
+
+      # Detects the environment from a token string by parsing its prefix.
+      # Useful for displaying environment info when you only have the token.
+      #
+      # @param token [String] The full token string (e.g., "sk_test_abc123...")
+      # @return [Symbol, nil] The detected environment (:test, :live, etc.) or nil
+      #
+      # @example
+      #   api_key_environment_from_token("sk_test_abc123") # => :test
+      #   api_key_environment_from_token("pk_live_xyz789") # => :live
+      #   api_key_environment_from_token("ak_abc123")      # => nil
+      #
+      def api_key_environment_from_token(token)
+        return nil if token.blank?
+        return nil if token.length > 500 # Reasonable max length for tokens
+
+        config = ApiKeys.configuration
+        return nil unless config.environments.present?
+
+        # Check each configured environment's prefix segment
+        config.environments.each do |env_name, env_config|
+          segment = env_config[:prefix_segment]
+          next if segment.blank?
+
+          # Match pattern like _test_ or _live_ in the token
+          if token.include?("_#{segment}_")
+            return env_name
+          end
+        end
+
+        nil
+      end
+
+      # Returns a human-readable environment label from a token string.
+      # Convenience wrapper around api_key_environment_from_token.
+      #
+      # @param token [String] The full token string
+      # @return [String] "Test mode", "Live mode", or "Default" if unknown
+      #
+      # @example
+      #   api_key_environment_label_from_token("sk_test_abc") # => "Test mode"
+      #   api_key_environment_label_from_token("sk_live_xyz") # => "Live mode"
+      #
+      def api_key_environment_label_from_token(token)
+        env = api_key_environment_from_token(token)
+        return "Default" if env.nil?
+
+        "#{env.to_s.capitalize} mode"
+      end
+
+      # Returns a hash of status information for an API key.
+      # Useful for building custom status badges.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [Hash] Hash with :status, :label, and :color keys
+      #
+      # @example
+      #   info = api_key_status_info(@key)
+      #   # => { status: :active, label: "Active", color: :green }
+      #
+      def api_key_status_info(api_key)
+        status = api_key_status(api_key)
+        {
+          status: status,
+          label: api_key_status_label(api_key),
+          color: status_color(status)
+        }
+      end
+
+      # Returns a hash of type information for an API key.
+      # Useful for building custom type badges.
+      #
+      # @param api_key [ApiKeys::ApiKey] The API key
+      # @return [Hash] Hash with :type, :label, and :color keys
+      #
+      # @example
+      #   info = api_key_type_info(@key)
+      #   # => { type: :publishable, label: "Publishable", color: :green }
+      #
+      def api_key_type_info(api_key)
+        type = api_key.key_type.presence&.to_sym || :secret
+        {
+          type: type,
+          label: api_key_type_label(api_key),
+          color: type_color(type)
+        }
+      end
+
+      private
+
+      def status_color(status)
+        case status
+        when :active then :green
+        when :expired then :red
+        when :revoked then :gray
+        else :gray
+        end
+      end
+
+      def type_color(type)
+        case type
+        when :publishable then :green
+        when :secret then :amber
+        else :gray
+        end
+      end
+    end
+  end
+end