rsb-admin 0.9.1

data/app/helpers/rsb/admin/i18n_helper.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # View helper methods for internationalization (i18n) in the admin panel.
+    #
+    # This helper provides scoped translation methods and label resolution
+    # with fallback chains for columns, filters, and form fields.
+    #
+    # The helper is automatically included in all RSB::Admin controllers
+    # via the AdminController base class.
+    #
+    # @example In a view
+    #   <%= rsb_admin_t("shared.save") %>
+    #   # => "Save"
+    #
+    # @example Resolving column labels with fallback
+    #   <%= rsb_admin_column_label(column, resource_key: "users") %>
+    #   # Tries: rsb.admin.resources.users.columns.email
+    #   # Falls back to: rsb.admin.columns.email
+    #   # Falls back to: column.label
+    module I18nHelper
+      # Shorthand for admin-scoped i18n lookups.
+      #
+      # Prefixes the given key with `rsb.admin.` and delegates to Rails' `t()` helper.
+      # This keeps view code concise and DRY.
+      #
+      # @param key [String, Symbol] the i18n key relative to `rsb.admin`
+      # @param options [Hash] options to pass to `I18n.t` (e.g., interpolation values)
+      #
+      # @return [String] the translated string
+      #
+      # @example Basic usage
+      #   rsb_admin_t("shared.save")
+      #   # => "Save"
+      #
+      # @example With interpolation
+      #   rsb_admin_t("shared.new", resource: "User")
+      #   # => "New User"
+      #
+      # @example With count for pluralization
+      #   rsb_admin_t("shared.showing", from: 1, to: 25, total: 100)
+      #   # => "Showing 1-25 of 100"
+      def rsb_admin_t(key, **options)
+        I18n.t("rsb.admin.#{key}", **options)
+      end
+
+      # Resolve a column label through i18n with fallbacks.
+      #
+      # The label resolution follows a 4-level fallback chain:
+      # 1. Per-resource i18n key: `rsb.admin.resources.#{resource_key}.columns.#{column.key}` (if resource_key provided)
+      # 2. Global column i18n key: `rsb.admin.columns.#{column.key}`
+      # 3. DSL-provided label from ColumnDefinition (column.label)
+      # 4. Humanized key (already the default for column.label)
+      #
+      # This allows per-resource overrides (e.g., "Identity Email" for identities),
+      # global column names (e.g., "Email" for all resources), and DSL-level defaults.
+      #
+      # @param column [ColumnDefinition] the column definition object
+      # @param resource_key [String, Symbol, nil] optional resource key for per-resource translations
+      #
+      # @return [String] the resolved label
+      #
+      # @example With global i18n
+      #   col = ColumnDefinition.build(:email, label: "Fallback")
+      #   rsb_admin_column_label(col)
+      #   # => "Email" (from rsb.admin.columns.email)
+      #
+      # @example With per-resource override
+      #   rsb_admin_column_label(col, resource_key: "identities")
+      #   # => "Identity Email" (from rsb.admin.resources.identities.columns.email)
+      #
+      # @example Falls back to DSL label
+      #   col = ColumnDefinition.build(:custom_field, label: "My Custom Field")
+      #   rsb_admin_column_label(col)
+      #   # => "My Custom Field" (DSL label, no i18n key exists)
+      def rsb_admin_column_label(column, resource_key: nil)
+        if resource_key
+          result = I18n.t("rsb.admin.resources.#{resource_key}.columns.#{column.key}", default: nil)
+          return result if result
+        end
+
+        global = I18n.t("rsb.admin.columns.#{column.key}", default: nil)
+        return global if global
+
+        column.label
+      end
+
+      # Resolve a filter label through i18n with fallbacks.
+      #
+      # The label resolution follows a fallback chain:
+      # 1. Per-resource i18n key: `rsb.admin.resources.#{resource_key}.filters.#{filter.key}` (if resource_key provided)
+      # 2. DSL-provided label from FilterDefinition (filter.label)
+      #
+      # @param filter [FilterDefinition] the filter definition object
+      # @param resource_key [String, Symbol, nil] optional resource key for per-resource translations
+      #
+      # @return [String] the resolved label
+      #
+      # @example With per-resource i18n
+      #   filter = FilterDefinition.build(:status, label: "Fallback")
+      #   rsb_admin_filter_label(filter, resource_key: "users")
+      #   # => "User Status" (from rsb.admin.resources.users.filters.status)
+      #
+      # @example Falls back to DSL label
+      #   filter = FilterDefinition.build(:custom, label: "Custom Filter")
+      #   rsb_admin_filter_label(filter)
+      #   # => "Custom Filter" (DSL label, no i18n key exists)
+      def rsb_admin_filter_label(filter, resource_key: nil)
+        if resource_key
+          result = I18n.t("rsb.admin.resources.#{resource_key}.filters.#{filter.key}", default: nil)
+          return result if result
+        end
+
+        filter.label
+      end
+
+      # Resolve a form field label through i18n with fallbacks.
+      #
+      # The label resolution follows a fallback chain:
+      # 1. Per-resource i18n key: `rsb.admin.resources.#{resource_key}.fields.#{field.key}` (if resource_key provided)
+      # 2. DSL-provided label from FormFieldDefinition (field.label)
+      #
+      # @param field [FormFieldDefinition] the form field definition object
+      # @param resource_key [String, Symbol, nil] optional resource key for per-resource translations
+      #
+      # @return [String] the resolved label
+      #
+      # @example With per-resource i18n
+      #   field = FormFieldDefinition.build(:email, label: "Fallback")
+      #   rsb_admin_field_label(field, resource_key: "users")
+      #   # => "User Email Address" (from rsb.admin.resources.users.fields.email)
+      #
+      # @example Falls back to DSL label
+      #   field = FormFieldDefinition.build(:custom, label: "Custom Field")
+      #   rsb_admin_field_label(field)
+      #   # => "Custom Field" (DSL label, no i18n key exists)
+      def rsb_admin_field_label(field, resource_key: nil)
+        if resource_key
+          result = I18n.t("rsb.admin.resources.#{resource_key}.fields.#{field.key}", default: nil)
+          return result if result
+        end
+
+        field.label
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/icons_helper.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # View helper methods for rendering Lucide icons in admin panel views.
+    #
+    # This helper is automatically included in all RSB::Admin controllers
+    # via the AdminController base class.
+    #
+    # @example In a view
+    #   <%= rsb_admin_icon("users") %>
+    #   <%= rsb_admin_icon("home", size: 24, css_class: "text-blue-500") %>
+    module IconsHelper
+      # Render a Lucide icon SVG with optional CSS class.
+      #
+      # Wraps {RSB::Admin::Icons.render} and optionally injects a CSS class
+      # into the SVG tag. The class value is HTML-escaped to prevent XSS.
+      # If the icon is not found, returns an empty string (no error - rule #9).
+      #
+      # @param name [String, Symbol] The icon name (e.g., "users", :home)
+      # @param size [Integer] The width and height of the icon in pixels
+      # @param css_class [String, nil] Optional CSS class to add to the SVG tag
+      #
+      # @return [ActiveSupport::SafeBuffer] HTML-safe SVG string with optional class, or empty string if icon not found
+      #
+      # @example Basic usage
+      #   rsb_admin_icon("users")
+      #   # => '<svg xmlns="..." width="18" height="18" ...>...</svg>'
+      #
+      # @example With custom size
+      #   rsb_admin_icon("home", size: 24)
+      #   # => '<svg xmlns="..." width="24" height="24" ...>...</svg>'
+      #
+      # @example With CSS class
+      #   rsb_admin_icon("settings", css_class: "icon-lg text-gray-600")
+      #   # => '<svg class="icon-lg text-gray-600" xmlns="..." ...>...</svg>'
+      #
+      # @example Unknown icon returns empty string
+      #   rsb_admin_icon("nonexistent")
+      #   # => ""
+      #
+      # @example XSS-safe (class is HTML-escaped)
+      #   rsb_admin_icon("users", css_class: '"><script>alert("xss")</script>')
+      #   # => '<svg class="&quot;&gt;&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;" ...>...</svg>'
+      def rsb_admin_icon(name, size: 18, css_class: nil)
+        svg = RSB::Admin::Icons.render(name, size: size)
+        if css_class && svg.present?
+          svg.sub('<svg ', "<svg class=\"#{ERB::Util.html_escape(css_class)}\" ").html_safe
+        else
+          svg
+        end
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/table_helper.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # View helper methods for generating sortable table links and preserving filter state.
+    #
+    # This helper provides utilities for building sort links that cycle through
+    # sort states (asc → desc → none) and preserve existing filter parameters
+    # in the URL. The helper is automatically included in all RSB::Admin
+    # controllers via the AdminController base class.
+    #
+    # @example In a view
+    #   <% columns.each do |col| %>
+    #     <% if col.sortable %>
+    #       <a href="<%= sort_link(col) %>"><%= col.label %></a>
+    #     <% else %>
+    #       <%= col.label %>
+    #     <% end %>
+    #   <% end %>
+    module TableHelper
+      # Build a sort link URL for a sortable column.
+      #
+      # This method generates a URL that includes sort and direction parameters,
+      # and preserves any existing filter query parameters. The sort direction
+      # cycles through three states when clicking the same column repeatedly:
+      # 1. No sort → asc
+      # 2. asc → desc
+      # 3. desc → no sort (removes sort parameters)
+      #
+      # When clicking a different column, it always starts with asc direction.
+      #
+      # @param column [ColumnDefinition] the column definition object
+      #
+      # @return [String] the URL with sort parameters and preserved filters
+      #
+      # @example First click on a column (no sort → asc)
+      #   sort_link(column)
+      #   # => "/admin/users?sort=email&dir=asc"
+      #
+      # @example Second click on same column (asc → desc)
+      #   # Given: params[:sort] = "email", params[:dir] = "asc"
+      #   sort_link(column)
+      #   # => "/admin/users?sort=email&dir=desc"
+      #
+      # @example Third click on same column (desc → none)
+      #   # Given: params[:sort] = "email", params[:dir] = "desc"
+      #   sort_link(column)
+      #   # => "/admin/users"
+      #
+      # @example Preserves existing filters
+      #   # Given: params[:q] = { status: "active" }, params[:sort] = "email", params[:dir] = "asc"
+      #   sort_link(column)
+      #   # => "/admin/users?sort=email&dir=desc&q[status]=active"
+      #
+      # @example Clicking different column resets to asc
+      #   # Given: params[:sort] = "email", params[:dir] = "desc"
+      #   sort_link(name_column)
+      #   # => "/admin/users?sort=name&dir=asc"
+      def sort_link(column)
+        current_sort = params[:sort]
+        current_dir = params[:dir]
+
+        # Determine new direction based on current state
+        new_dir = if current_sort == column.key.to_s
+                    # Clicking same column: cycle through asc → desc → none
+                    case current_dir
+                    when 'asc'
+                      'desc'
+                    when 'desc'
+                      nil # Remove sort
+                    else
+                      'asc'
+                    end
+                  else
+                    # Clicking different column: start with asc
+                    'asc'
+                  end
+
+        # Build URL with or without sort parameters
+        if new_dir
+          "#{request.path}?sort=#{column.key}&dir=#{new_dir}#{filter_query_string}"
+        elsif filter_query_string.present?
+          # No sort - just path + filters
+          "#{request.path}#{filter_query_string}"
+        else
+          request.path
+        end
+      end
+
+      private
+
+      # Build a query string from filter parameters.
+      #
+      # This method extracts filter parameters from `params[:q]` and converts
+      # them into a URL-encoded query string that can be appended to URLs.
+      # The query string is prefixed with "&" for easy concatenation with
+      # existing parameters.
+      #
+      # Special characters in filter values are properly URL-encoded to prevent
+      # issues with spaces, ampersands, and other special characters.
+      #
+      # @return [String] the URL-encoded query string prefixed with "&", or empty string if no filters
+      #
+      # @example No filters
+      #   filter_query_string
+      #   # => ""
+      #
+      # @example Single filter
+      #   # Given: params[:q] = { status: "active" }
+      #   filter_query_string
+      #   # => "&q[status]=active"
+      #
+      # @example Multiple filters
+      #   # Given: params[:q] = { status: "active", email: "test@example.com" }
+      #   filter_query_string
+      #   # => "&q[status]=active&q[email]=test%40example.com"
+      #
+      # @example Special characters are URL-encoded
+      #   # Given: params[:q] = { title: "test & value" }
+      #   filter_query_string
+      #   # => "&q[title]=test+%26+value"
+      #
+      # @api private
+      def filter_query_string
+        return '' unless params[:q].present?
+
+        filter_hash = params[:q].respond_to?(:to_unsafe_h) ? params[:q].to_unsafe_h : params[:q]
+        '&' + filter_hash.map { |k, v| "q[#{k}]=#{ERB::Util.url_encode(v)}" }.join('&')
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/theme_helper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # View helper methods for theme-aware partial resolution in admin panel views.
+    #
+    # This helper provides a partial resolution system that follows a 3-level
+    # override chain, allowing host applications and themes to override engine
+    # default views. The helper is automatically included in all RSB::Admin
+    # controllers via the AdminController base class.
+    #
+    # @see RSB::Admin::Configuration#view_overrides_path
+    # @see RSB::Admin::Configuration#theme
+    # @see RSB::Admin::ThemeDefinition
+    #
+    # @example In a view
+    #   <%= render rsb_admin_partial("shared/sidebar") %>
+    #   # Resolves to first match:
+    #   # 1. app/views/admin_overrides/shared/_sidebar.html.erb (if view_overrides_path set)
+    #   # 2. app/views/rsb/admin/themes/modern/views/shared/_sidebar.html.erb (if theme has views_path)
+    #   # 3. rsb-admin/app/views/rsb/admin/shared/_sidebar.html.erb (engine default)
+    module ThemeHelper
+      # Resolves a partial path through the theme override chain.
+      #
+      # This method implements the view override resolution order (rule #16):
+      # 1. Host app override path (highest priority)
+      # 2. Theme override path
+      # 3. Engine default (fallback)
+      #
+      # The resolved path is returned as a string suitable for passing to `render`.
+      # This method is designed to be used with the `render` helper in views (rule #14).
+      #
+      # @param name [String] The partial name without leading underscore or extension
+      #   (e.g., "shared/sidebar", "users/form")
+      #
+      # @return [String] The resolved partial path
+      #
+      # @example Basic usage (no overrides)
+      #   rsb_admin_partial("shared/sidebar")
+      #   # => "rsb/admin/shared/sidebar"
+      #
+      # @example With host app override
+      #   # Given: RSB::Admin.configuration.view_overrides_path = "admin_overrides"
+      #   # And file exists: app/views/admin_overrides/shared/_sidebar.html.erb
+      #   rsb_admin_partial("shared/sidebar")
+      #   # => "admin_overrides/shared/sidebar"
+      #
+      # @example With theme override
+      #   # Given: RSB::Admin.configuration.theme = :modern
+      #   # And theme.views_path = "rsb/admin/themes/modern/views"
+      #   # And file exists: app/views/rsb/admin/themes/modern/views/shared/_sidebar.html.erb
+      #   rsb_admin_partial("shared/sidebar")
+      #   # => "rsb/admin/themes/modern/views/shared/sidebar"
+      #
+      # @example Priority order
+      #   # Host app override takes precedence over theme override
+      #   # Theme override takes precedence over engine default
+      #   rsb_admin_partial("users/form")
+      #   # Checks in order:
+      #   # 1. admin_overrides/users/_form.html.erb
+      #   # 2. rsb/admin/themes/modern/views/users/_form.html.erb
+      #   # 3. rsb/admin/users/_form.html.erb (always returned as fallback)
+      def rsb_admin_partial(name)
+        override_path = RSB::Admin.configuration.view_overrides_path
+        theme = RSB::Admin.current_theme
+
+        # 1. Host app override (highest priority)
+        if override_path
+          candidate = "#{override_path}/#{name}"
+          return candidate if lookup_context.exists?(candidate, [], true)
+        end
+
+        # 2. Theme override
+        if theme&.views_path
+          candidate = "#{theme.views_path}/#{name}"
+          return candidate if lookup_context.exists?(candidate, [], true)
+        end
+
+        # 3. Engine default (fallback)
+        "rsb/admin/#{name}"
+      end
+    end
+  end
+end

data/app/helpers/rsb/admin/url_helper.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Dynamic URL helpers for admin resource and page paths.
+    #
+    # These helpers derive all URLs from the engine mount point (extracted from
+    # rsb_admin.dashboard_path) so they work correctly regardless of where the
+    # engine is mounted. They replace hardcoded "/admin/..." strings throughout
+    # views and controllers.
+    #
+    # @example In a view
+    #   rsb_admin_resource_path("identities")         # => "/admin/identities"
+    #   rsb_admin_resource_show_path("identities", 42) # => "/admin/identities/42"
+    #
+    module UrlHelper
+      # Generate the index path for a resource.
+      #
+      # @param route_key [String] the resource's route key (e.g., "identities")
+      # @return [String] e.g., "/admin/identities"
+      #
+      # @example
+      #   rsb_admin_resource_path("identities") # => "/admin/identities"
+      def rsb_admin_resource_path(route_key)
+        "#{rsb_admin_base_path}#{route_key}"
+      end
+
+      # Generate the show path for a specific resource record.
+      #
+      # @param route_key [String]
+      # @param id [Integer, String]
+      # @return [String] e.g., "/admin/identities/42"
+      #
+      # @example
+      #   rsb_admin_resource_show_path("identities", 42) # => "/admin/identities/42"
+      def rsb_admin_resource_show_path(route_key, id)
+        "#{rsb_admin_base_path}#{route_key}/#{id}"
+      end
+
+      # Generate the new path for creating a resource record.
+      #
+      # @param route_key [String]
+      # @return [String] e.g., "/admin/identities/new"
+      #
+      # @example
+      #   rsb_admin_resource_new_path("identities") # => "/admin/identities/new"
+      def rsb_admin_resource_new_path(route_key)
+        "#{rsb_admin_base_path}#{route_key}/new"
+      end
+
+      # Generate the edit path for a specific resource record.
+      #
+      # @param route_key [String]
+      # @param id [Integer, String]
+      # @return [String] e.g., "/admin/identities/42/edit"
+      #
+      # @example
+      #   rsb_admin_resource_edit_path("identities", 42) # => "/admin/identities/42/edit"
+      def rsb_admin_resource_edit_path(route_key, id)
+        "#{rsb_admin_base_path}#{route_key}/#{id}/edit"
+      end
+
+      # Generate the path for a static page.
+      #
+      # @param page_key [String, Symbol]
+      # @return [String] e.g., "/admin/active_sessions"
+      #
+      # @example
+      #   rsb_admin_page_path("active_sessions") # => "/admin/active_sessions"
+      def rsb_admin_page_path(page_key)
+        "#{rsb_admin_base_path}#{page_key}"
+      end
+
+      # Generate the path for a static page action.
+      #
+      # @param page_key [String, Symbol]
+      # @param action_key [String, Symbol]
+      # @return [String] e.g., "/admin/active_sessions/by_user"
+      #
+      # @example
+      #   rsb_admin_page_action_path("active_sessions", "by_user") # => "/admin/active_sessions/by_user"
+      def rsb_admin_page_action_path(page_key, action_key)
+        "#{rsb_admin_base_path}#{page_key}/#{action_key}"
+      end
+
+      # Generate the path for a dashboard sub-action.
+      #
+      # @param action_key [String, Symbol] the action key (e.g., "metrics")
+      # @return [String] e.g., "/admin/dashboard/metrics"
+      #
+      # @example
+      #   rsb_admin_dashboard_action_path("metrics") # => "/admin/dashboard/metrics"
+      def rsb_admin_dashboard_action_path(action_key)
+        "#{rsb_admin_base_path}dashboard/#{action_key}"
+      end
+
+      private
+
+      # Extract the engine mount point from the dashboard path.
+      # Returns the mount point with trailing slash (e.g., "/admin/").
+      #
+      # @return [String] the engine mount point with trailing slash
+      # @api private
+      def rsb_admin_base_path
+        @rsb_admin_base_path ||= rsb_admin.dashboard_path.chomp('dashboard')
+      end
+    end
+  end
+end

data/app/mailers/rsb/admin/admin_mailer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Mailer for admin panel transactional emails.
+    #
+    # Uses the host app's ActionMailer configuration (SMTP settings, delivery method).
+    # The `from` address is configurable via `RSB::Admin.configuration.mailer_sender`.
+    #
+    # @example Send verification email
+    #   AdminMailer.email_verification(admin_user).deliver_later
+    #
+    class AdminMailer < ActionMailer::Base
+      # Sends a verification link to the admin's pending email address.
+      #
+      # @param admin_user [AdminUser] must have `pending_email` and `email_verification_token` set
+      # @return [Mail::Message]
+      def email_verification(admin_user)
+        @admin_user = admin_user
+        @verification_url = verify_email_url(admin_user.email_verification_token)
+
+        mail(
+          to: admin_user.pending_email,
+          from: RSB::Admin.configuration.mailer_sender,
+          subject: 'Verify your new email address'
+        )
+      end
+
+      private
+
+      def verify_email_url(token)
+        RSB::Admin::Engine.routes.url_helpers.verify_email_profile_url(token: token,
+                                                                       host: default_url_options[:host] || 'localhost')
+      end
+    end
+  end
+end

data/app/models/rsb/admin/admin_session.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RSB
+  module Admin
+    # Represents an active admin session with device and location tracking.
+    #
+    # Each sign-in creates an AdminSession record with a unique token stored in
+    # the cookie session. The token replaces the plain user ID for security.
+    # Device information is parsed from the User-Agent header.
+    #
+    # @example Create a session from a request
+    #   session = AdminSession.create_from_request!(admin_user: user, request: request)
+    #   session.session_token # => "abc123..."
+    #   session.browser       # => "Chrome"
+    #   session.os            # => "macOS"
+    #
+    class AdminSession < ApplicationRecord
+      belongs_to :admin_user
+
+      validates :session_token, presence: true, uniqueness: true
+      validates :last_active_at, presence: true
+
+      before_validation :generate_session_token, on: :create
+
+      # Parses a User-Agent string into browser, OS, and device type.
+      # Uses simple regex matching — no external gem dependency.
+      #
+      # @param user_agent [String, nil] the raw User-Agent header
+      # @return [Hash{Symbol => String}] keys: :browser, :os, :device_type
+      #
+      # @example
+      #   AdminSession.parse_user_agent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36")
+      #   # => { browser: "Chrome", os: "macOS", device_type: "desktop" }
+      def self.parse_user_agent(user_agent)
+        ua = user_agent.to_s
+
+        browser = case ua
+                  when %r{Edg/}i then 'Edge'
+                  when %r{OPR/}i, /Opera/i then 'Opera'
+                  when /Chrome/i then 'Chrome'
+                  when /Firefox/i then 'Firefox'
+                  when /Safari/i then 'Safari'
+                  else 'Unknown'
+                  end
+
+        os = case ua
+             when /Windows/i then 'Windows'
+             when /iPhone|iPad/i then 'iOS'
+             when /Android/i then 'Android'
+             when /Macintosh|Mac OS/i then 'macOS'
+             when /Linux/i then 'Linux'
+             else 'Unknown'
+             end
+
+        device_type = case ua
+                      when /Mobile|iPhone|Android.*Mobile/i then 'mobile'
+                      when /iPad|Tablet|Android(?!.*Mobile)/i then 'tablet'
+                      else 'desktop'
+                      end
+
+        { browser: browser, os: os, device_type: device_type }
+      end
+
+      # Creates a session record for the given admin user from a request.
+      #
+      # Parses the User-Agent header for device info, records IP address,
+      # and generates a unique session token.
+      #
+      # @param admin_user [AdminUser] the authenticated admin
+      # @param request [ActionDispatch::Request] the current request
+      # @return [AdminSession] the persisted session record
+      # @raise [ActiveRecord::RecordInvalid] if validation fails
+      def self.create_from_request!(admin_user:, request:)
+        parsed = parse_user_agent(request.user_agent)
+
+        create!(
+          admin_user: admin_user,
+          ip_address: request.remote_ip,
+          user_agent: request.user_agent,
+          browser: parsed[:browser],
+          os: parsed[:os],
+          device_type: parsed[:device_type],
+          last_active_at: Time.current
+        )
+      end
+
+      # Checks if this session matches the given token (i.e., is the "current" session).
+      #
+      # @param token [String] the session token from the cookie
+      # @return [Boolean]
+      def current?(token)
+        session_token == token
+      end
+
+      # Updates last_active_at without triggering callbacks or updating updated_at.
+      #
+      # @return [void]
+      def touch_activity!
+        update_column(:last_active_at, Time.current)
+      end
+
+      private
+
+      def generate_session_token
+        self.session_token ||= SecureRandom.urlsafe_base64(32)
+      end
+    end
+  end
+end