railspress-engine 1.2.0 → 1.3.0

data/app/controllers/railspress/api/v1/base_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      class BaseController < ActionController::API
+        include ActionController::HttpAuthentication::Token::ControllerMethods
+
+        before_action :ensure_api_enabled!
+        before_action :authenticate_api_key!
+
+        rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+
+        attr_reader :current_api_key
+
+        private
+
+        def ensure_api_enabled!
+          render_error("API is not enabled.", status: :not_found) unless Railspress.api_enabled?
+        end
+
+        def authenticate_api_key!
+          return if authenticate_with_http_token { |token, _opts| authenticate_with_token(token) }
+
+          render_error("Unauthorized", status: :unauthorized)
+        end
+
+        def authenticate_with_token(token)
+          @current_api_key = Railspress::ApiKey.authenticate(token, ip_address: request.remote_ip)
+          @current_api_key.present?
+        end
+
+        def render_not_found
+          render_error("Resource not found.", status: :not_found)
+        end
+
+        def render_validation_errors(record)
+          render json: {
+            error: {
+              message: "Validation failed.",
+              details: record.errors.full_messages
+            }
+          }, status: :unprocessable_content
+        end
+
+        def render_error(message, status:)
+          render json: { error: { message: message } }, status: status
+        end
+      end
+    end
+  end
+end

data/app/controllers/railspress/api/v1/categories_controller.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      class CategoriesController < BaseController
+        before_action :set_category, only: [ :show, :update, :destroy ]
+
+        def index
+          categories = Railspress::Category.ordered
+          total_count = categories.count
+          categories = categories.offset((page - 1) * per_page).limit(per_page)
+
+          render json: {
+            data: categories.map { |category| serialize_category(category) },
+            meta: {
+              page: page,
+              per: per_page,
+              total_count: total_count,
+              total_pages: (total_count.to_f / per_page).ceil
+            }
+          }
+        end
+
+        def show
+          render json: { data: serialize_category(@category) }
+        end
+
+        def create
+          category = Railspress::Category.new(category_params)
+
+          if category.save
+            render json: { data: serialize_category(category) }, status: :created
+          else
+            render_validation_errors(category)
+          end
+        end
+
+        def update
+          if @category.update(category_params)
+            render json: { data: serialize_category(@category) }
+          else
+            render_validation_errors(@category)
+          end
+        end
+
+        def destroy
+          if @category.destroy
+            head :no_content
+          else
+            render_validation_errors(@category)
+          end
+        end
+
+        private
+
+        def set_category
+          @category = Railspress::Category.find(params[:id])
+        end
+
+        def category_params
+          params.require(:category).permit(:name, :slug, :description)
+        end
+
+        def page
+          [ params.fetch(:page, 1).to_i, 1 ].max
+        end
+
+        def per_page
+          requested = params.fetch(:per, 20).to_i
+          requested = 20 if requested <= 0
+          [ requested, 100 ].min
+        end
+
+        def serialize_category(category)
+          {
+            id: category.id,
+            name: category.name,
+            slug: category.slug,
+            description: category.description,
+            posts_count: category.posts.count,
+            created_at: category.created_at,
+            updated_at: category.updated_at
+          }
+        end
+      end
+    end
+  end
+end

data/app/controllers/railspress/api/v1/concerns/post_serialization.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      module Concerns
+        module PostSerialization
+          private
+
+          def serialize_post(post)
+            {
+              id: post.id,
+              title: post.title,
+              slug: post.slug,
+              status: post.status,
+              published_at: post.published_at,
+              reading_time: post.reading_time_display,
+              meta_title: post.meta_title,
+              meta_description: post.meta_description,
+              category_id: post.category_id,
+              author_id: post.author_id,
+              author_display: serialize_author_display(post),
+              tag_list: post.tag_list,
+              content: post.content&.to_s,
+              header_image: serialize_header_image(post),
+              header_image_focal_point: serialize_header_image_focal_point(post),
+              created_at: post.created_at,
+              updated_at: post.updated_at
+            }
+          end
+
+          def serialize_header_image(post)
+            return nil unless Railspress.post_images_enabled?
+            return { attached: false } unless post.header_image.attached?
+
+            blob = post.header_image.blob
+
+            {
+              attached: true,
+              blob_id: blob.id,
+              signed_blob_id: blob.signed_id,
+              filename: blob.filename.to_s,
+              byte_size: blob.byte_size,
+              content_type: blob.content_type
+            }
+          end
+
+          def serialize_focal_point(focal_point)
+            {
+              id: focal_point.id,
+              attachment_name: focal_point.attachment_name,
+              focal_x: focal_point.focal_x.to_f,
+              focal_y: focal_point.focal_y.to_f,
+              overrides: focal_point.overrides || {}
+            }
+          end
+
+          def serialize_header_image_focal_point(post)
+            return nil unless Railspress.post_images_enabled? && Railspress.focal_points_enabled?
+            return nil unless post.header_image.attached?
+
+            focal_point = post.header_image_focal_point
+            focal_point.save! if focal_point.new_record?
+            serialize_focal_point(focal_point)
+          end
+
+          def serialize_header_image_context(post, context_name, context_config: nil)
+            context_name = context_name.to_s
+            context_config ||= Railspress.image_contexts[context_name.to_sym]
+            override = post.image_override(context_name, :header_image)
+
+            {
+              name: context_name,
+              label: context_config&.dig(:label) || context_name.humanize,
+              aspect: context_config&.dig(:aspect),
+              sizes: context_config&.dig(:sizes) || [],
+              has_override: post.has_image_override?(context_name, :header_image),
+              override: serialize_context_override(override),
+              image_css: post.image_css_for(context_name, :header_image),
+              image: serialize_context_image(post, context_name, override)
+            }
+          end
+
+          def serialize_author_display(post)
+            return nil unless Railspress.authors_enabled?
+            return nil unless post.author.present?
+
+            configured_method = Railspress.author_display_method
+            if configured_method.present? && post.author.respond_to?(configured_method)
+              configured_value = post.author.public_send(configured_method)
+              return configured_value if configured_value.present?
+            end
+
+            fallback_method = [ :name, :full_name, :display_name, :email, :email_address ]
+              .find { |method| post.author.respond_to?(method) && post.author.public_send(method).present? }
+
+            fallback_method ? post.author.public_send(fallback_method) : "Author ##{post.author.id || "unknown"}"
+          end
+
+          def serialize_context_override(override)
+            return { type: "focal" } if override.blank?
+
+            override.to_h.deep_stringify_keys
+          end
+
+          def serialize_context_image(post, context_name, override)
+            image = post.image_for(context_name, :header_image)
+            blob = if image.is_a?(ActiveStorage::Blob)
+              image
+            elsif image.respond_to?(:blob)
+              image.blob
+            end
+            return nil unless blob.present?
+
+            override_type = override&.dig(:type) || override&.dig("type")
+
+            {
+              source: override_type == "upload" ? "upload_override" : "header_image",
+              blob_id: blob.id,
+              signed_blob_id: blob.signed_id,
+              filename: blob.filename.to_s,
+              byte_size: blob.byte_size,
+              content_type: blob.content_type
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/railspress/api/v1/post_header_image_contexts_controller.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      class PostHeaderImageContextsController < BaseController
+        include Railspress::Api::V1::Concerns::PostSerialization
+
+        rescue_from ActionController::BadRequest, with: :render_unprocessable_request
+
+        before_action :ensure_post_images_enabled!
+        before_action :ensure_focal_points_enabled!
+        before_action :set_post
+        before_action :ensure_header_image_attached!
+        before_action :set_context, only: [ :show, :update, :destroy ]
+
+        def index
+          render json: {
+            data: available_contexts.map do |context_name, context_config|
+              serialize_header_image_context(@post, context_name, context_config: context_config)
+            end
+          }
+        end
+
+        def show
+          render json: { data: serialize_header_image_context(@post, @context_name, context_config: @context_config) }
+        end
+
+        def update
+          apply_context_override!
+          return if performed?
+
+          render json: {
+            data: serialize_header_image_context(@post, @context_name, context_config: @context_config),
+            post: serialize_post(@post.reload)
+          }
+        rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+          render_error("Invalid signed blob id.", status: :unprocessable_content)
+        end
+
+        def destroy
+          @post.clear_image_override(@context_name, :header_image)
+          @post.save!
+
+          render json: {
+            data: serialize_header_image_context(@post, @context_name, context_config: @context_config),
+            post: serialize_post(@post.reload)
+          }
+        end
+
+        private
+
+        def ensure_post_images_enabled!
+          render_error("Post images are not enabled.", status: :not_found) unless Railspress.post_images_enabled?
+        end
+
+        def ensure_focal_points_enabled!
+          render_error("Focal points are not enabled.", status: :not_found) unless Railspress.focal_points_enabled?
+        end
+
+        def set_post
+          @post = Railspress::Post.find(params[:post_id])
+        end
+
+        def ensure_header_image_attached!
+          render_error("Header image is not attached.", status: :unprocessable_content) unless @post.header_image.attached?
+        end
+
+        def set_context
+          @context_name = params[:context].to_s
+          @context_config = available_contexts[@context_name.to_sym]
+          return if @context_config.present?
+
+          render_error("Image context not found.", status: :not_found)
+        end
+
+        def available_contexts
+          @available_contexts ||= Railspress.image_contexts || {}
+        end
+
+        def apply_context_override!
+          override = override_params
+
+          case override[:type]
+          when "focal"
+            @post.clear_image_override(@context_name, :header_image)
+          when "crop"
+            @post.set_image_override(@context_name, {
+              "type" => "crop",
+              "region" => normalize_crop_region(override[:region])
+            }, :header_image)
+          when "upload"
+            @post.set_image_override(@context_name, {
+              "type" => "upload",
+              "blob_signed_id" => signed_blob_id_for_upload(override)
+            }, :header_image)
+          else
+            return render_error("Override type must be one of: focal, crop, upload.", status: :unprocessable_content)
+          end
+
+          return if @post.save
+
+          render_validation_errors(@post.header_image_focal_point)
+        end
+
+        def override_params
+          params.require(:override).permit(:type, :signed_blob_id, :blob_signed_id, region: [ :x, :y, :width, :height ])
+        end
+
+        def normalize_crop_region(raw_region)
+          unless raw_region.present?
+            raise ActionController::BadRequest, "Crop overrides require a region hash."
+          end
+
+          region = raw_region.to_h.transform_values { |value| Float(value) }
+          validate_crop_region!(region)
+
+          {
+            "x" => region.fetch("x").to_f,
+            "y" => region.fetch("y").to_f,
+            "width" => region.fetch("width").to_f,
+            "height" => region.fetch("height").to_f
+          }
+        rescue KeyError
+          raise ActionController::BadRequest, "Crop region must include x, y, width, and height."
+        rescue ArgumentError
+          raise ActionController::BadRequest, "Crop region values must be numeric."
+        end
+
+        def validate_crop_region!(region)
+          values = [ region.fetch("x"), region.fetch("y"), region.fetch("width"), region.fetch("height") ]
+          if values.any? { |value| value.negative? || value > 1 }
+            raise ActionController::BadRequest, "Crop region values must stay within 0..1."
+          end
+
+          if region.fetch("width").zero? || region.fetch("height").zero?
+            raise ActionController::BadRequest, "Crop region width and height must be greater than 0."
+          end
+
+          if region.fetch("x") + region.fetch("width") > 1 || region.fetch("y") + region.fetch("height") > 1
+            raise ActionController::BadRequest, "Crop region must fit within the source image bounds."
+          end
+        end
+
+        def signed_blob_id_for_upload(override)
+          signed_blob_id = override[:signed_blob_id].presence || override[:blob_signed_id].presence
+          raise ActionController::BadRequest, "Upload overrides require signed_blob_id." if signed_blob_id.blank?
+
+          ActiveStorage::Blob.find_signed!(signed_blob_id).signed_id
+        end
+
+        def render_unprocessable_request(error)
+          render_error(error.message, status: :unprocessable_content)
+        end
+      end
+    end
+  end
+end

data/app/controllers/railspress/api/v1/post_header_image_focal_points_controller.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      class PostHeaderImageFocalPointsController < BaseController
+        include Railspress::Api::V1::Concerns::PostSerialization
+
+        before_action :ensure_post_images_enabled!
+        before_action :ensure_focal_points_enabled!
+        before_action :set_post
+        before_action :ensure_header_image_attached!
+
+        def show
+          render json: { data: serialize_focal_point(current_focal_point) }
+        end
+
+        def update
+          focal_point = current_focal_point
+
+          if focal_point.update(focal_point_params)
+            render json: {
+              data: serialize_focal_point(focal_point),
+              post: serialize_post(@post.reload)
+            }
+          else
+            render_validation_errors(focal_point)
+          end
+        end
+
+        private
+
+        def ensure_post_images_enabled!
+          render_error("Post images are not enabled.", status: :not_found) unless Railspress.post_images_enabled?
+        end
+
+        def ensure_focal_points_enabled!
+          render_error("Focal points are not enabled.", status: :not_found) unless Railspress.focal_points_enabled?
+        end
+
+        def set_post
+          @post = Railspress::Post.find(params[:post_id])
+        end
+
+        def ensure_header_image_attached!
+          render_error("Header image is not attached.", status: :unprocessable_content) unless @post.header_image.attached?
+        end
+
+        def current_focal_point
+          focal_point = @post.header_image_focal_point
+          focal_point.save! if focal_point.new_record?
+          focal_point
+        end
+
+        def focal_point_params
+          permitted = params.require(:focal_point).permit(:focal_x, :focal_y, overrides: {})
+          permitted[:overrides] = normalize_overrides(permitted[:overrides])
+          permitted
+        end
+
+        def normalize_overrides(overrides)
+          return {} if overrides.blank?
+          return overrides.to_unsafe_h if overrides.is_a?(ActionController::Parameters)
+          return overrides if overrides.is_a?(Hash)
+          return JSON.parse(overrides) if overrides.is_a?(String)
+
+          {}
+        rescue JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end

data/app/controllers/railspress/api/v1/post_header_images_controller.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      class PostHeaderImagesController < BaseController
+        include Railspress::Api::V1::Concerns::PostSerialization
+
+        before_action :ensure_post_images_enabled!
+        before_action :set_post
+
+        def show
+          return render_error("Header image not found.", status: :not_found) unless @post.header_image.attached?
+
+          render json: {
+            data: {
+              post_id: @post.id,
+              header_image: serialize_header_image(@post),
+              header_image_focal_point: serialize_header_image_focal_point(@post)
+            }
+          }
+        end
+
+        def update
+          image = header_image_param
+          return render_error("Either image or signed_blob_id is required.", status: :unprocessable_content) if image.blank?
+
+          @post.header_image.attach(image)
+          render json: { data: serialize_post(@post.reload) }
+        rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+          render_error("Invalid signed blob id.", status: :unprocessable_content)
+        end
+
+        def destroy
+          @post.header_image.purge if @post.header_image.attached?
+          head :no_content
+        end
+
+        private
+
+        def ensure_post_images_enabled!
+          render_error("Post images are not enabled.", status: :not_found) unless Railspress.post_images_enabled?
+        end
+
+        def set_post
+          @post = Railspress::Post.find(params[:post_id])
+        end
+
+        def header_image_param
+          return params[:image] if params[:image].present?
+          return if params[:signed_blob_id].blank?
+
+          ActiveStorage::Blob.find_signed!(params[:signed_blob_id])
+        end
+      end
+    end
+  end
+end

data/app/controllers/railspress/api/v1/post_imports_controller.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Railspress
+  module Api
+    module V1
+      class PostImportsController < BaseController
+        SUPPORTED_EXTENSIONS = %w[.md .markdown .txt .zip].freeze
+
+        before_action :set_import, only: [ :show ]
+
+        def create
+          source = import_source
+          return render_error("Either file or signed_blob_id is required.", status: :unprocessable_content) unless source
+
+          unless supported_file?(source[:filename])
+            return render_error("Unsupported import file type. Allowed: .md, .markdown, .txt, .zip.", status: :unprocessable_content)
+          end
+
+          import = Railspress::Import.create!(
+            import_type: "posts",
+            filename: source[:filename],
+            content_type: source[:content_type],
+            status: "pending",
+            user_id: current_api_key&.owner_id
+          )
+
+          file_path = persist_import_file(import, source)
+          Railspress::ImportPostsJob.perform_later(import.id, [ file_path ])
+
+          render json: { data: serialize_import(import.reload) }, status: :accepted
+        rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+          render_error("Invalid signed blob id.", status: :unprocessable_content)
+        rescue => error
+          Rails.logger.warn("Failed to create post import via API: #{error.class} #{error.message}")
+          render_error("Failed to queue import.", status: :unprocessable_content)
+        end
+
+        def show
+          render json: { data: serialize_import(@import) }
+        end
+
+        private
+
+        def set_import
+          @import = Railspress::Import.where(import_type: "posts").find(params[:id])
+        end
+
+        def import_source
+          upload = params[:file] || params.dig(:import, :file)
+          return upload_source(upload) if upload.present?
+
+          signed_blob_id = params[:signed_blob_id] || params.dig(:import, :signed_blob_id)
+          return nil if signed_blob_id.blank?
+
+          blob_source(ActiveStorage::Blob.find_signed!(signed_blob_id))
+        end
+
+        def upload_source(upload)
+          {
+            type: :upload,
+            value: upload,
+            filename: upload.original_filename,
+            content_type: upload.content_type
+          }
+        end
+
+        def blob_source(blob)
+          {
+            type: :blob,
+            value: blob,
+            filename: blob.filename.to_s,
+            content_type: blob.content_type
+          }
+        end
+
+        def supported_file?(filename)
+          extension = File.extname(filename.to_s).downcase
+          SUPPORTED_EXTENSIONS.include?(extension)
+        end
+
+        def persist_import_file(import, source)
+          upload_dir = Rails.root.join("tmp", "uploads", "import_#{import.id}")
+          FileUtils.mkdir_p(upload_dir)
+
+          filename = File.basename(source[:filename].to_s)
+          destination = upload_dir.join(filename)
+
+          case source[:type]
+          when :upload
+            FileUtils.cp(source[:value].path, destination)
+          when :blob
+            source[:value].open do |file|
+              FileUtils.cp(file.path, destination)
+            end
+          end
+
+          destination.to_s
+        end
+
+        def serialize_import(import)
+          {
+            id: import.id,
+            import_type: import.import_type,
+            filename: import.filename,
+            content_type: import.content_type,
+            status: import.status,
+            total_count: import.total_count,
+            success_count: import.success_count,
+            error_count: import.error_count,
+            error_messages: import.parsed_errors,
+            created_at: import.created_at,
+            updated_at: import.updated_at
+          }
+        end
+      end
+    end
+  end
+end