rails_onboarding 0.6.1

data/lib/rails_onboarding/api_mode.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # API Mode support for headless/API-only applications
+  # Provides JSON API endpoints for mobile apps and SPAs
+  module ApiMode
+    extend ActiveSupport::Concern
+
+    included do
+      # Skip CSRF for API requests (only works with ActionController classes)
+      begin
+        skip_before_action :verify_authenticity_token, if: :api_request?, raise: false
+      rescue NoMethodError
+        # Not an ActionController class, skip this setup
+      end
+
+      # Set API response format (only works with ActionController classes)
+      begin
+        before_action :set_api_response_format, if: :api_request?
+      rescue NoMethodError
+        # Not an ActionController class, skip this setup
+      end
+
+      # Error handling (only works with ActionController classes)
+      begin
+        rescue_from StandardError, with: :handle_api_error if :api_request?
+      rescue NoMethodError
+        # Not an ActionController class, skip this setup
+      end
+    end
+
+    module ClassMethods
+      # Enable API mode for specific actions
+      def enable_api_mode(options = {})
+        @api_mode_options = {
+          version: options.fetch(:version, "v1"),
+          authentication: options.fetch(:authentication, :token),
+          serializer: options.fetch(:serializer, :active_model_serializers),
+          rate_limiting: options.fetch(:rate_limiting, true),
+          pagination: options.fetch(:pagination, true)
+        }.merge(options)
+      end
+
+      def api_mode_options
+        @api_mode_options || {}
+      end
+
+      # Check if API mode is enabled
+      def api_mode_enabled?
+        @api_mode_options.present?
+      end
+    end
+
+    # Detect API requests
+    def api_request?
+      request.format.json? ||
+      request.path.start_with?("/api/") ||
+      request.headers["Accept"]&.include?("application/json") ||
+      request.headers["Content-Type"]&.include?("application/json")
+    end
+
+    # API response helpers
+    def render_api_success(data, status: :ok, meta: {})
+      render json: {
+        success: true,
+        data: serialize_for_api(data),
+        meta: build_api_meta(meta)
+      }, status: status
+    end
+
+    def render_api_error(message, status: :unprocessable_entity, errors: {})
+      render json: {
+        success: false,
+        error: {
+          message: message,
+          details: errors
+        },
+        meta: build_api_meta
+      }, status: status
+    end
+
+    # Onboarding-specific API methods
+    def api_onboarding_status
+      render_api_success({
+        onboarding_completed: current_user.onboarding_completed?,
+        onboarding_skipped: current_user.onboarding_skipped?,
+        current_step: current_user.onboarding_current_step,
+        progress_percentage: current_user.onboarding_progress_percentage,
+        steps: api_format_steps,
+        next_step: api_next_step,
+        previous_step: api_previous_step
+      })
+    end
+
+    def api_complete_step
+      step_name = params[:step_name] || params[:step]
+
+      if current_user.complete_step(step_name)
+        render_api_success({
+          message: "Step '#{step_name}' completed successfully",
+          current_step: current_user.onboarding_current_step,
+          progress_percentage: current_user.onboarding_progress_percentage,
+          onboarding_completed: current_user.onboarding_completed?
+        })
+      else
+        render_api_error("Failed to complete step '#{step_name}'", errors: current_user.errors.full_messages)
+      end
+    end
+
+    def api_skip_step
+      step_name = params[:step_name] || params[:step]
+
+      if current_user.skip_step(step_name)
+        render_api_success({
+          message: "Step '#{step_name}' skipped successfully",
+          current_step: current_user.onboarding_current_step,
+          progress_percentage: current_user.onboarding_progress_percentage
+        })
+      else
+        render_api_error("Failed to skip step '#{step_name}'", errors: current_user.errors.full_messages)
+      end
+    end
+
+    def api_complete_onboarding
+      if current_user.complete_onboarding!
+        render_api_success({
+          message: "Onboarding completed successfully",
+          completed_at: current_user.onboarding_completed_at
+        })
+      else
+        render_api_error("Failed to complete onboarding", errors: current_user.errors.full_messages)
+      end
+    end
+
+    def api_restart_onboarding
+      if current_user.restart_onboarding!
+        render_api_success({
+          message: "Onboarding restarted successfully",
+          current_step: current_user.onboarding_current_step,
+          progress_percentage: 0
+        })
+      else
+        render_api_error("Failed to restart onboarding", errors: current_user.errors.full_messages)
+      end
+    end
+
+    def api_tooltips_list
+      tooltips = current_user.available_tooltips
+
+      render_api_success({
+        tooltips: tooltips.map do |tooltip|
+          {
+            id: tooltip[:id],
+            title: tooltip[:title],
+            content: tooltip[:content],
+            target: tooltip[:target],
+            position: tooltip[:position],
+            shown: current_user.tooltip_shown?(tooltip[:id])
+          }
+        end
+      })
+    end
+
+    def api_dismiss_tooltip
+      tooltip_id = params[:tooltip_id]
+
+      if current_user.dismiss_tooltip(tooltip_id)
+        render_api_success({
+          message: "Tooltip dismissed successfully",
+          tooltip_id: tooltip_id
+        })
+      else
+        render_api_error("Failed to dismiss tooltip")
+      end
+    end
+
+    # API authentication
+    def authenticate_api_request!
+      return if current_user.present?
+
+      token = extract_api_token
+
+      if token.blank?
+        render_api_error("Missing authentication token", status: :unauthorized)
+        return
+      end
+
+      user = authenticate_with_token(token)
+
+      if user
+        # Set current_user for the request
+        instance_variable_set(:@current_user, user)
+      else
+        render_api_error("Invalid authentication token", status: :unauthorized)
+      end
+    end
+
+    # Current user accessor for API requests
+    def current_user
+      @current_user ||= begin
+        token = extract_api_token
+        authenticate_with_token(token) if token.present?
+      end
+    end
+
+    private
+
+    # Serialize data for API response
+    def serialize_for_api(data)
+      case self.class.api_mode_options[:serializer]
+      when :active_model_serializers
+        # Use ActiveModel::Serializers if available
+        if defined?(ActiveModel::Serializer)
+          ActiveModelSerializers::SerializableResource.new(data).as_json
+        else
+          data.as_json
+        end
+      when :jsonapi
+        # Use JSONAPI::Serializer if available
+        if defined?(JSONAPI::Serializer)
+          data.to_json
+        else
+          data.as_json
+        end
+      else
+        # Default to as_json
+        data.respond_to?(:as_json) ? data.as_json : data
+      end
+    end
+
+    # Build API metadata
+    def build_api_meta(custom_meta = {})
+      {
+        timestamp: Time.current.iso8601,
+        version: self.class.api_mode_options[:version] || "v1",
+        request_id: request.request_id
+      }.merge(custom_meta)
+    end
+
+    # Format steps for API
+    def api_format_steps
+      RailsOnboarding.configuration.steps.map do |step|
+        {
+          name: step[:name],
+          title: step[:title],
+          description: step[:description],
+          icon: step[:icon],
+          skippable: step[:skippable],
+          completed: current_user.step_completed?(step[:name])
+        }
+      end
+    end
+
+    # Get next step for API
+    def api_next_step
+      next_step = current_user.next_step
+      return nil unless next_step
+
+      {
+        name: next_step[:name],
+        title: next_step[:title],
+        description: next_step[:description]
+      }
+    end
+
+    # Get previous step for API
+    def api_previous_step
+      prev_step = current_user.previous_step
+      return nil unless prev_step
+
+      {
+        name: prev_step[:name],
+        title: prev_step[:title],
+        description: prev_step[:description]
+      }
+    end
+
+    # Extract the API token from the request. Tokens are only read from
+    # request headers, never from query parameters: a token in the URL leaks
+    # into server and proxy access logs, browser history, and the Referer
+    # header sent to third parties.
+    def extract_api_token
+      authorization = request.headers["Authorization"]
+      # Authorization: Bearer <token> (also tolerates a bare token value)
+      return authorization.split(" ").last if authorization.present?
+
+      # Custom header for clients that can't set Authorization
+      request.headers["X-API-Token"].presence
+    end
+
+    # Authenticate user with token
+    def authenticate_with_token(token)
+      # This should be implemented by the host application
+      # Default implementation uses a simple token check
+      user_class = RailsOnboarding.configuration.user_class_name.constantize
+
+      if user_class.respond_to?(:find_by_api_token)
+        user_class.find_by_api_token(token)
+      elsif user_class.column_names.include?("api_token")
+        user_class.find_by(api_token: token)
+      else
+        # Raise error if no token authentication method is available
+        raise NotImplementedError,
+          "API token authentication not configured. Please add an 'api_token' column to your User model " \
+          "or implement a custom 'find_by_api_token' class method. See documentation for more details."
+      end
+    end
+
+    # Set API response format
+    def set_api_response_format
+      request.format = :json
+    end
+
+    # Handle API errors
+    def handle_api_error(exception)
+      Rails.logger.error("API Error: #{exception.class} - #{exception.message}")
+      Rails.logger.error(exception.backtrace.join("\n"))
+
+      render_api_error(
+        "An error occurred: #{exception.message}",
+        status: :internal_server_error
+      )
+    end
+  end
+
+  # API Controller for dedicated API endpoints
+  class ApiController < ActionController::API
+    include RailsOnboarding::ApiMode
+
+    before_action :authenticate_api_request!
+
+    # GET /api/onboarding/status
+    def status
+      api_onboarding_status
+    end
+
+    # POST /api/onboarding/steps/:step_name/complete
+    def complete_step
+      api_complete_step
+    end
+
+    # POST /api/onboarding/steps/:step_name/skip
+    def skip_step
+      api_skip_step
+    end
+
+    # POST /api/onboarding/complete
+    def complete
+      api_complete_onboarding
+    end
+
+    # POST /api/onboarding/restart
+    def restart
+      api_restart_onboarding
+    end
+
+    # GET /api/onboarding/tooltips
+    def tooltips
+      api_tooltips_list
+    end
+
+    # POST /api/onboarding/tooltips/:tooltip_id/dismiss
+    def dismiss_tooltip
+      api_dismiss_tooltip
+    end
+  end
+end

data/lib/rails_onboarding/backfill.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RailsOnboarding
+  # One-shot data fixes for applications that installed RailsOnboarding on top
+  # of an existing users table.
+  #
+  # Users who signed up before the gem was installed have NULL onboarding
+  # columns, so the admin reports them as "Not Started" and - depending on the
+  # +onboarding_required_for+ strategy - they can be pushed back through a flow
+  # they have no business seeing. Backfilling marks them as already onboarded.
+  #
+  # Everything here writes with +update_all+ in batches: no callbacks, no
+  # validations, and deliberately no analytics events. Backfilled users never
+  # went through onboarding, so recording completion events for them would put
+  # fiction into the funnel metrics.
+  module Backfill
+    DEFAULT_BATCH_SIZE = 1_000
+
+    REQUIRED_COLUMNS = %w[
+      onboarding_completed
+      onboarding_completed_at
+      onboarding_current_step
+    ].freeze
+
+    Result = Struct.new(:matched, :updated, :dry_run, keyword_init: true) do
+      def dry_run?
+        dry_run
+      end
+    end
+
+    class << self
+      # Marks pre-existing users as having finished onboarding.
+      #
+      # Only users who have never engaged with onboarding are touched: not
+      # completed, not skipped, and sitting on no current step. Anyone
+      # mid-flow is left alone so a backfill can be re-run safely while the
+      # app is live.
+      #
+      # @param created_before [Time, Date, String, nil] restrict to users
+      #   created before this moment. Users with a NULL +created_at+ are
+      #   always included when a cutoff is given - a row with no creation
+      #   timestamp predates any cutoff worth naming, and those rows are
+      #   exactly the legacy ones this task exists for.
+      # @param completed_at [Time] timestamp used for users whose +created_at+
+      #   is NULL. Users with a +created_at+ get their own signup time, which
+      #   keeps completion-over-time charts from spiking on backfill day.
+      # @param batch_size [Integer] rows per UPDATE statement.
+      # @param dry_run [Boolean] count the affected rows without writing.
+      # @return [Result]
+      def mark_existing_users_onboarded(created_before: nil, completed_at: Time.current,
+        batch_size: DEFAULT_BATCH_SIZE, dry_run: false)
+        ensure_columns!
+
+        scope = pending_scope(created_before: created_before)
+        matched = scope.count
+        return Result.new(matched: matched, updated: 0, dry_run: true) if dry_run
+
+        updated = 0
+        scope.in_batches(of: batch_size) do |batch|
+          updated += batch.update_all(completion_assignment(completed_at))
+        end
+
+        Result.new(matched: matched, updated: updated, dry_run: false)
+      end
+
+      # Users the backfill would touch. Exposed so callers can inspect or
+      # further narrow the set before running.
+      def pending_scope(created_before: nil)
+        scope = user_class
+          .where(onboarding_current_step: nil)
+          .where(onboarding_completed: [ false, nil ])
+
+        scope = scope.where(onboarding_skipped: [ false, nil ]) if column?("onboarding_skipped")
+        return scope unless created_before
+
+        cutoff = normalize_time(created_before)
+        scope.where("#{quoted_table}.created_at < ? OR #{quoted_table}.created_at IS NULL", cutoff)
+      end
+
+      def user_class
+        RailsOnboarding.configuration.user_class_name.constantize
+      end
+
+      private
+
+      def completion_assignment(fallback_completed_at)
+        assignments = [
+          "onboarding_completed = ?",
+          "onboarding_completed_at = COALESCE(#{quoted_table}.created_at, ?)"
+        ]
+        values = [ true, normalize_time(fallback_completed_at) ]
+
+        # Columns added with `default: false` but no NOT NULL constraint can
+        # still hold NULL on rows written before the default landed, which
+        # makes `onboarding_skipped?` return nil-ish garbage in the admin.
+        if column?("onboarding_skipped")
+          assignments << "onboarding_skipped = COALESCE(#{quoted_table}.onboarding_skipped, ?)"
+          values << false
+        end
+
+        user_class.sanitize_sql_for_assignment([ assignments.join(", "), *values ])
+      end
+
+      def ensure_columns!
+        missing = REQUIRED_COLUMNS.reject { |name| column?(name) }
+        return if missing.empty?
+
+        raise ArgumentError,
+          "#{user_class.name} is missing onboarding columns: #{missing.join(', ')}. " \
+          "Run the RailsOnboarding install migrations first."
+      end
+
+      def column?(name)
+        user_class.column_names.include?(name)
+      end
+
+      def quoted_table
+        user_class.connection.quote_table_name(user_class.table_name)
+      end
+
+      def normalize_time(value)
+        case value
+        when String then Time.zone ? Time.zone.parse(value) : Time.parse(value)
+        when Date then value.to_time
+        else value
+        end
+      end
+    end
+  end
+end