rails-markup 1.2.0

data/app/controllers/rails_markup/annotations_controller.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module RailsMarkup
+  class AnnotationsController < RailsMarkup.config.base_controller_class.constantize
+    protect_from_forgery with: :exception
+
+    before_action :set_annotation, only: %i[acknowledge resolve dismiss reply]
+
+    rescue_from ActiveRecord::RecordNotFound do
+      render json: { error: "not found" }, status: :not_found
+    end
+
+    # POST /feedback/api/sessions
+    def create_session
+      render json: { id: "rm-#{SecureRandom.hex(8)}", url: params[:url] }
+    end
+
+    # POST /feedback/api/sessions/:session_id/annotations
+    def create
+      return render_invalid_metadata if client_supplied_author?
+
+      attributes = annotation_params
+      return render_invalid_legacy_client_id unless attributes
+
+      annotation = Annotation.new(attributes)
+      assign_current_user(annotation)
+
+      if annotation.client_uuid.present? && (existing = Annotation.find_by(client_uuid: annotation.client_uuid))
+        return render_duplicate(existing, annotation)
+      end
+
+      if annotation.save
+        fire_create_callback(annotation)
+        render json: annotation.as_api_json, status: :created
+      else
+        render json: { errors: annotation.errors.full_messages }, status: :unprocessable_entity
+      end
+    rescue ActiveRecord::RecordNotUnique
+      raise if annotation.client_uuid.blank?
+
+      render_duplicate(Annotation.find_by!(client_uuid: annotation.client_uuid), annotation)
+    end
+
+    # GET /feedback/api/annotations?page_url=/current?page=variant
+    def index
+      annotations = Annotation.for_page(params[:page_url]).recent.to_a
+      unless annotations.all? { |annotation| Annotation.valid_client_uuid?(annotation.client_uuid) }
+        return render json: { error: "annotation identities require repair" }, status: :service_unavailable
+      end
+
+      render json: annotations.map(&:as_api_json)
+    end
+
+    # PUT /feedback/api/annotations/:client_uuid
+    def upsert
+      client_uuid = normalized_route_uuid
+      return render_invalid_uuid unless client_uuid
+      return render_invalid_metadata if client_supplied_author?
+
+      dirty_fields = normalized_dirty_fields
+      return render_invalid_dirty_fields unless dirty_fields
+
+      attributes = browser_attributes
+      return render_invalid_status if dirty_fields.include?("status") && !Annotation::STATUSES.include?(attributes["status"])
+
+      annotation = Annotation.find_or_initialize_by(client_uuid: client_uuid)
+      created = annotation.new_record?
+      apply_desired_state(annotation, attributes, dirty_fields)
+      annotation.save!
+      fire_create_callback(annotation) if created
+      render json: annotation.as_api_json
+    rescue ActiveRecord::RecordInvalid => error
+      render json: { errors: error.record.errors.full_messages }, status: :unprocessable_entity
+    rescue ActiveRecord::RecordNotUnique
+      annotation = Annotation.find_by!(client_uuid: client_uuid)
+      apply_desired_state(annotation, attributes, dirty_fields)
+      annotation.save!
+      render json: annotation.as_api_json
+    end
+
+    # DELETE /feedback/api/annotations/:client_uuid
+    def destroy
+      client_uuid = normalized_route_uuid
+      return render_invalid_uuid unless client_uuid
+
+      Annotation.find_by(client_uuid: client_uuid)&.destroy!
+      head :no_content
+    end
+
+    # GET /feedback/api/health
+    def health
+      render json: { ok: true }
+    end
+
+    # POST /feedback/api/annotations/:id/acknowledge
+    def acknowledge
+      @annotation.acknowledge!
+      render json: @annotation.as_api_json
+    end
+
+    # POST /feedback/api/annotations/:id/resolve
+    def resolve
+      @annotation.resolve!(summary: params[:summary])
+      render json: @annotation.as_api_json
+    end
+
+    # POST /feedback/api/annotations/:id/dismiss
+    def dismiss
+      @annotation.dismiss!(reason: params[:reason])
+      render json: @annotation.as_api_json
+    end
+
+    # POST /feedback/api/annotations/:id/reply
+    def reply
+      return render json: { error: "message is required" }, status: :unprocessable_entity if params[:message].blank?
+
+      @annotation.add_reply!(message: params[:message], role: "agent")
+      render json: @annotation.as_api_json
+    end
+
+    private
+
+    def set_annotation
+      @annotation = Annotation.find(params[:id])
+    end
+
+    DEDUP_ATTRIBUTES = %w[user_id page_url content intent severity selected_text target metadata].freeze
+
+    def assign_current_user(annotation)
+      return unless respond_to?(:current_user, true) && current_user
+
+      annotation.user_id = current_user.id
+      author = RailsMarkup.config.resolve_author_name(current_user)
+      annotation.metadata = (annotation.metadata || {}).merge("author" => author) if author
+    end
+
+    def render_duplicate(existing, candidate)
+      if existing.attributes.slice(*DEDUP_ATTRIBUTES) == candidate.attributes.slice(*DEDUP_ATTRIBUTES)
+        render json: existing.as_api_json, status: :ok
+      else
+        render json: { error: "client id already used for a different annotation" }, status: :conflict
+      end
+    end
+
+    ALLOWED_TARGET_KEYS = %w[selector cssPath nearbyText boundingBox].freeze
+    ALLOWED_METADATA_KEYS = Annotation::BROWSER_METADATA_KEYS.freeze
+    ALLOWED_DIRTY_FIELDS = (Annotation::BROWSER_ATTRIBUTES + %w[metadata status]).freeze
+    DIRTY_FIELD_ALIASES = { "selectedText" => "selected_text" }.freeze
+
+    def fire_create_callback(annotation)
+      callback = RailsMarkup.config.on_create_callback
+      return unless callback.respond_to?(:call)
+
+      callback.call(annotation)
+    rescue => e
+      Rails.logger.error("[rails-markup] on_create_callback error: #{e.message}")
+    end
+
+    def annotation_params
+      permitted = params.permit(:page_url, :content, :intent, :severity, :selected_text, :selectedText, :clientId, target: {}, metadata: {})
+      permitted[:selected_text] ||= permitted.delete(:selectedText)
+      requested_client_uuid = permitted.delete(:clientId).to_s.strip
+      if (normalized_client_uuid = Annotation.normalize_client_uuid(requested_client_uuid))
+        permitted[:client_uuid] = normalized_client_uuid
+      elsif requested_client_uuid.present?
+        permitted[:client_uuid] = Annotation.legacy_client_uuid(
+          session_id: params[:session_id], legacy_client_id: requested_client_uuid
+        )
+      end
+      permitted[:page_url] ||= request.referer || "/"
+      permitted[:target] = normalize_target(params[:target]) if params[:target].present?
+      permitted[:metadata] = normalize_hash(params[:metadata], ALLOWED_METADATA_KEYS) if params[:metadata].present?
+      permitted
+    rescue ArgumentError
+      nil
+    end
+
+    def browser_attributes
+      permitted = params.permit(:page_url, :content, :intent, :severity, :status, :selected_text, :selectedText, target: {}, metadata: {})
+      permitted[:selected_text] ||= permitted.delete(:selectedText)
+      permitted[:target] = normalize_target(params[:target]) if params.key?(:target)
+      permitted[:metadata] = normalize_hash(params[:metadata], ALLOWED_METADATA_KEYS) if params.key?(:metadata)
+      permitted.to_h.stringify_keys
+    end
+
+    def apply_desired_state(annotation, attributes, dirty_fields)
+      assign_current_user(annotation) if annotation.new_record?
+      annotation.apply_browser_state(attributes, dirty_fields: dirty_fields)
+    end
+
+    def normalized_route_uuid
+      uuid = params[:client_uuid].to_s.strip
+      Annotation.normalize_client_uuid(uuid)
+    end
+
+    def normalized_dirty_fields
+      fields = params[:dirtyFields] || []
+      return unless fields.is_a?(Array)
+
+      fields = fields.map { |field| DIRTY_FIELD_ALIASES.fetch(field.to_s, field.to_s) }
+      fields if (fields - ALLOWED_DIRTY_FIELDS).empty?
+    end
+
+    def client_supplied_author?
+      metadata = params[:metadata]
+      metadata.respond_to?(:key?) && (metadata.key?(:author) || metadata.key?("author"))
+    end
+
+    def render_invalid_uuid
+      render json: { error: "client uuid must be a canonical UUID" }, status: :unprocessable_entity
+    end
+
+    def render_invalid_legacy_client_id
+      render json: { error: "legacy client id requires a valid session identity" }, status: :unprocessable_entity
+    end
+
+    def render_invalid_metadata
+      render json: { error: "author metadata is server owned" }, status: :unprocessable_entity
+    end
+
+    def render_invalid_dirty_fields
+      render json: { error: "invalid dirty fields" }, status: :unprocessable_entity
+    end
+
+    def render_invalid_status
+      render json: { error: "invalid status" }, status: :unprocessable_entity
+    end
+
+    def normalize_target(target)
+      case target
+      when String then { "selector" => target }
+      when ActionController::Parameters
+        target.permit(*ALLOWED_TARGET_KEYS, boundingBox: %i[x y top left width height]).to_h
+      else {}
+      end
+    end
+
+    def normalize_hash(value, allowed_keys)
+      return {} unless value.is_a?(ActionController::Parameters)
+
+      value.permit(*allowed_keys).to_h
+    end
+  end
+end

data/app/controllers/rails_markup/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsMarkup
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/rails_markup/dashboard_controller.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module RailsMarkup
+  class DashboardController < RailsMarkup.config.base_controller_class.constantize
+    layout -> { RailsMarkup.config.dashboard_layout }
+
+    # When using a host app layout, expose host route helpers and all
+    # view helpers (icon, super_admin?, etc.) so the layout renders correctly.
+    if RailsMarkup.config.dashboard_layout != "rails_markup/application"
+      base = RailsMarkup.config.base_controller_class.constantize
+      helper base._helpers
+
+      # Delegate unknown *_path/*_url helpers to main_app so host routes
+      # don't get the engine mount prefix (/admin/annotations) prepended.
+      host_routes = Module.new do
+        def method_missing(method, *args, **kwargs, &block)
+          if method.to_s.match?(/_(path|url)\z/) && main_app.respond_to?(method)
+            main_app.public_send(method, *args, **kwargs, &block)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          (method.to_s.match?(/_(path|url)\z/) && main_app.respond_to?(method)) || super
+        end
+      end
+      helper host_routes
+
+      # Include helpers that gems add directly to ActionView::Base
+      ActionView::Base.included_modules.each do |mod|
+        next unless mod.is_a?(Module) && mod.name&.include?("Helper")
+        next if mod.name.start_with?("RailsMarkup")
+        helper mod rescue nil
+      end
+    end
+
+    ALLOWED_STATUSES = %w[all pending acknowledged resolved dismissed].freeze
+    ALLOWED_ROLES = %w[agent user].freeze
+
+    before_action :set_annotation, only: %i[show update]
+
+    # GET /feedback
+    def index
+      @current_status = ALLOWED_STATUSES.include?(params[:status]) ? params[:status] : "pending"
+      base_scope = build_base_scope
+
+      # Single grouped count query instead of 6 separate queries
+      counts = base_scope.group(:status).count
+      @total_count = counts.values.sum
+      @pending_count = counts["pending"] || 0
+      @acknowledged_count = counts["acknowledged"] || 0
+      @resolved_count = counts["resolved"] || 0
+      @dismissed_count = counts["dismissed"] || 0
+
+      paginate(filtered_scope)
+
+      @page_urls = Annotation.distinct.pluck(:page_url).sort
+      @current_page_url = params[:page_url]
+      @authors = Annotation.distinct_authors
+      @current_author = params[:author]
+      @current_query = params[:q]
+    end
+
+    # GET /feedback/annotations/:id
+    def show
+    end
+
+    # GET /feedback/load_more
+    def load_more
+      @current_status = ALLOWED_STATUSES.include?(params[:status]) ? params[:status] : "pending"
+      @current_page_url = params[:page_url]
+      @current_author = params[:author]
+      @current_query = params[:q]
+
+      # load_more only ever fetches the NEXT page. A missing/invalid cursor
+      # (stale ?page= link, malformed cursor) must not silently re-serve page
+      # one, which would append duplicate cards. Return an empty page instead.
+      if valid_cursor?
+        paginate(filtered_scope)
+      else
+        @annotations = []
+        @next_page = false
+        @remaining = 0
+      end
+
+      render partial: "annotation_page", layout: false
+    end
+
+    # GET /feedback/board
+    def board
+      @columns = {
+        pending: Annotation.pending.recent.limit(50),
+        acknowledged: Annotation.acknowledged.recent.limit(50),
+        resolved: Annotation.resolved.recent.limit(20),
+        dismissed: Annotation.dismissed.recent.limit(20)
+      }
+    end
+
+    # POST /feedback/dismiss_all
+    def dismiss_all
+      status = params[:status]
+      unless status.in?(%w[pending acknowledged])
+        return redirect_to root_path, alert: "Invalid status for bulk dismiss."
+      end
+
+      count = Annotation.where(status: status).update_all(status: "dismissed")
+      redirect_to root_path(status: "dismissed"), notice: "#{count} annotations dismissed."
+    end
+
+    # PATCH /feedback/annotations/:id
+    def update
+      case params[:action_type]
+      when "acknowledge" then @annotation.acknowledge!
+      when "resolve"     then @annotation.resolve!(summary: params[:summary].presence)
+      when "dismiss"     then @annotation.dismiss!(reason: params[:reason].presence)
+      when "reply"
+        role = ALLOWED_ROLES.include?(params[:role]) ? params[:role] : "agent"
+        @annotation.add_reply!(message: params[:message], role: role)
+      when "transition"
+        new_status = params[:status]
+        if Annotation::STATUSES.include?(new_status)
+          @annotation.update!(status: new_status)
+          return head :ok
+        else
+          return render json: { error: "invalid status" }, status: :unprocessable_entity
+        end
+      else
+        return redirect_to annotation_path(@annotation), alert: "Unknown action."
+      end
+
+      redirect_to annotation_path(@annotation), notice: "Annotation updated."
+    end
+
+    # GET /feedback/export.csv
+    def export_csv
+      scope = build_export_scope
+      csv_data = generate_csv(scope)
+      send_data csv_data, filename: "annotations-#{Date.current}.csv", type: "text/csv"
+    end
+
+    # GET /feedback/export.json
+    def export_json
+      scope = build_export_scope
+      json_data = scope.map(&:as_api_json).to_json
+      send_data json_data, filename: "annotations-#{Date.current}.json", type: "application/json"
+    end
+
+    private
+
+    def set_annotation
+      @annotation = Annotation.find(params[:id])
+    end
+
+    def per_page
+      RailsMarkup.config.per_page
+    end
+
+    def build_base_scope
+      params[:page_url].present? ? Annotation.for_page(params[:page_url]) : Annotation.all
+    end
+
+    # Shared filtered, ordered scope for index + load_more. Requires @current_status.
+    def filtered_scope
+      scope = build_base_scope.recent
+      scope = scope.where(status: @current_status) unless @current_status == "all"
+      scope = scope.search(params[:q]) if params[:q].present?
+      scope = scope.by_author(params[:author]) if params[:author].present?
+      scope
+    end
+
+    # Keyset pagination: fetch one extra row to detect "more", and expose a
+    # (created_at, id) cursor for the next page instead of a page/offset — so a
+    # row inserted between requests can't push a boundary row onto two pages.
+    def paginate(scope)
+      cursor = scope
+      before_time = parse_cursor_time(params[:before_time])
+      if before_time && params[:before_id].present?
+        cursor = cursor.before_cursor(before_time, params[:before_id].to_i)
+      end
+
+      rows = cursor.limit(per_page + 1).to_a
+      @next_page = rows.size > per_page
+      @annotations = rows.first(per_page)
+
+      if @next_page && @annotations.any?
+        last = @annotations.last
+        @next_time = last.created_at.iso8601(6)
+        @next_id = last.id
+        @remaining = scope.before_cursor(last.created_at, last.id).count
+      else
+        @next_page = false
+        @next_time = @next_id = nil
+        @remaining = 0
+      end
+    end
+
+    def parse_cursor_time(value)
+      return nil if value.blank?
+
+      Time.zone.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    def valid_cursor?
+      params[:before_id].present? && parse_cursor_time(params[:before_time]).present?
+    end
+
+    def build_export_scope
+      scope = build_base_scope.recent
+      scope = scope.where(status: params[:status]) if params[:status].present? && params[:status] != "all"
+      scope = scope.search(params[:q]) if params[:q].present?
+      scope = scope.by_author(params[:author]) if params[:author].present?
+      scope
+    end
+
+    def generate_csv(scope)
+      CSV.generate(headers: true) do |csv|
+        csv << %w[id status intent severity content page_url author selected_text created_at updated_at]
+        scope.find_each do |ann|
+          csv << [ann.id, ann.status, ann.intent, ann.severity, ann.content, ann.page_url,
+                  ann.author_name, ann.selected_text, ann.created_at.iso8601, ann.updated_at.iso8601]
+        end
+      end
+    end
+  end
+end

data/app/controllers/rails_markup/external/annotations_controller.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RailsMarkup
+  module External
+    class AnnotationsController < ActionController::API
+      before_action :authenticate_token!
+      before_action :set_annotation, only: %i[show acknowledge resolve dismiss reply]
+
+      rescue_from ActiveRecord::RecordNotFound do
+        render json: { error: "not found" }, status: :not_found
+      end
+
+      # GET /external/pending
+      def pending
+        annotations = Annotation.pending.recent.limit(50)
+        render json: { annotations: annotations.map(&:as_api_json) }
+      end
+
+      # GET /external/:id
+      def show
+        render json: @annotation.as_api_json
+      end
+
+      # PATCH /external/:id/acknowledge
+      def acknowledge
+        @annotation.acknowledge!
+        render json: @annotation.as_api_json
+      end
+
+      # PATCH /external/:id/resolve
+      def resolve
+        @annotation.resolve!(summary: params[:summary])
+        render json: @annotation.as_api_json
+      end
+
+      # PATCH /external/:id/dismiss
+      def dismiss
+        @annotation.dismiss!(reason: params[:reason])
+        render json: @annotation.as_api_json
+      end
+
+      # PATCH /external/:id/reply
+      def reply
+        return render json: { error: "message is required" }, status: :unprocessable_entity if params[:message].blank?
+
+        @annotation.add_reply!(message: params[:message], role: "agent")
+        render json: @annotation.as_api_json
+      end
+
+      private
+
+      def set_annotation
+        @annotation = Annotation.find(params[:id])
+      end
+
+      def authenticate_token!
+        # Development — allow all requests without token (dev server may bind to LAN IP)
+        return if Rails.env.development?
+
+        token = RailsMarkup.config.api_token
+        return head(:not_found) if token.nil?
+
+        provided = request.headers["Authorization"]&.delete_prefix("Bearer ")
+        head(:unauthorized) unless ActiveSupport::SecurityUtils.secure_compare(provided.to_s, token)
+      end
+    end
+  end
+end