open_blog 0.1.0

data/lib/open_blog/label_policy.rb

@@ -0,0 +1,41 @@
+module OpenBlog
+  class LabelPolicy
+    def self.for(post)
+      new(post).label
+    end
+
+    def initialize(post)
+      @post = post
+    end
+
+    def label
+      return :none if @post.provenance_human_written?
+      notice = @post.provenance_ai_assisted? ? :ai_assisted : :ai_unknown
+      return notice if @post.provenance_ai_assisted? && OpenBlog.config.ai_label == :always
+      return notice unless OpenBlog.policy_url(:responsible_party).present?
+      return notice unless revision && @post.current_revision_identifier == revision.identifier
+      return notice unless image_digests_present?
+      return notice unless @post.approvals.where(revision_id: revision.id, facts_checked: true).exists?
+      :none
+    end
+
+    private
+
+    def revision
+      return @revision if defined?(@revision)
+      @revision = if @post.published?
+        @post.public_revision
+      else
+        @post.revisions.find_by(identifier: @post.current_revision_identifier)
+      end
+    end
+
+    def image_digests_present?
+      payload = JSON.parse(revision.payload)
+      images = payload["images"] if payload.is_a?(Hash)
+      images.is_a?(Array) && images.all? { |entry| entry.is_a?(Hash) && entry["sha256"].present? }
+    rescue JSON::ParserError
+      false
+    end
+  end
+end

data/lib/open_blog/markdown_view.rb

@@ -0,0 +1,57 @@
+module OpenBlog
+  class MarkdownView
+    def self.render(post, base_url: OpenBlog.config.public_base_url, now: Time.current)
+      new(post, base_url: base_url, now: now).render
+    end
+
+    def initialize(post, base_url:, now:)
+      @post, @base_url, @now = post, base_url, now
+    end
+
+    def render
+      parts = [ "# #{plain(@post.title)}", plain(@post.description).presence, byline, *notices, body ]
+      entries = @post.faq_list
+      if entries.any?
+        parts << "## #{plain(translate('faq.heading'))}"
+        entries.each { |entry| parts.concat([ "### #{plain(entry[:question])}", plain(entry[:answer]) ]) }
+      end
+      parts << (@post.canonical_url.presence || @post.url(base: @base_url) || @post.path)
+      "#{parts.compact.join("\n\n")}\n"
+    end
+
+    private
+
+    def body
+      @post.markdown? ? @post.body_markdown.to_s : plain(@post.rich_body.to_plain_text)
+    end
+
+    def byline
+      published = ReaderDates.published_at(@post, now: @now)
+      modified = ReaderDates.modified_at(@post, now: @now)
+      parts = [ @post.author_name ]
+      parts << date(published, :published) if published
+      parts << date(modified, :updated) if modified && (!published || modified > published)
+      plain(parts.join(" · "))
+    end
+
+    def date(time, label)
+      "#{translate("dates.#{label}")} #{I18n.l(time.to_date, format: :long, locale: OpenBlog.config.locale)}"
+    end
+
+    def notices
+      label = LabelPolicy.for(@post)
+      lines = label == :none ? [] : [ translate("notices.#{label}") ]
+      lines << translate("notices.paid") if @post.connection_declarations.order(id: :desc).first&.third_party_paid?
+      lines.map { |line| plain(line) }
+    end
+
+    def translate(key)
+      I18n.t("open_blog.#{key}", locale: OpenBlog.config.locale)
+    end
+
+    def plain(text)
+      text.to_s.gsub(/[\\`*_{}\[\]<>&!#|~+\-]/) { |character| "\\#{character}" }
+        .gsub(/^(\s*\d+)([.)])(?=\s)/) { "#{Regexp.last_match(1)}\\#{Regexp.last_match(2)}" }
+    end
+  end
+end

data/lib/open_blog/mcp/definition.rb

@@ -0,0 +1,28 @@
+module OpenBlog
+  module Mcp
+    class Definition
+      attr_reader :name, :title, :description, :input_schema, :annotations, :scope
+
+      def initialize(name:, title:, description:, input_schema:, annotations:, scope:, handler:)
+        @name, @title, @description = name, title, description
+        @input_schema, @annotations, @scope, @handler = input_schema, annotations, scope, handler
+        @validator = ::MCP::Tool::InputSchema.new(input_schema)
+      end
+
+      def call(arguments, actor:, base_url: nil)
+        raise Error::Unauthenticated unless actor
+        unless actor.respond_to?(:scopes) && actor.scopes.map(&:to_s).include?(scope.to_s)
+          raise Error::ScopeRequired.new(details: [ scope.to_s ])
+        end
+        raise Error::ValidationFailed.new(details: [ "arguments" ]) unless arguments.is_a?(Hash)
+        @validator.validate_arguments(arguments)
+        result = @handler.call(arguments.deep_symbolize_keys, actor: actor, base_url: base_url)
+        JSON.parse(JSON.generate(result))
+      rescue ::MCP::Tool::InputSchema::ValidationError
+        JSON.parse(JSON.generate(ErrorSerializer.call(Error::ValidationFailed.new(details: [ "arguments" ]))))
+      rescue Error => error
+        JSON.parse(JSON.generate(ErrorSerializer.call(error)))
+      end
+    end
+  end
+end

data/lib/open_blog/mcp/dispatcher.rb

@@ -0,0 +1,33 @@
+require "stringio"
+require "uri"
+
+module OpenBlog
+  module Mcp
+    class Dispatcher
+      CONTROLLERS = %w[posts approvals connections records findings doctor images categories tags authors series redirects adoptions faq_extractions previews pages views report].freeze
+      METHODS = %w[GET POST PUT PATCH DELETE].freeze
+
+      def self.call(controller:, action:, method:, arguments:, actor:, route_params: {}, base_url: nil)
+        raise ArgumentError, "Unknown publishing controller" unless CONTROLLERS.include?(controller.to_s)
+        verb = method.to_s.upcase
+        raise ArgumentError, "Unsupported request method" unless METHODS.include?(verb)
+        klass = "OpenBlog::Api::V1::#{controller.to_s.camelize}Controller".constantize
+        raise ArgumentError, "Unknown publishing action" unless klass.action_methods.include?(action.to_s)
+        origin = URI.parse(OpenBlog.config.public_base_url || base_url || "http://localhost")
+        env = { "REQUEST_METHOD" => verb, "SCRIPT_NAME" => "", "PATH_INFO" => "#{OpenBlog.mount_path}/api/v1/#{controller}",
+          "QUERY_STRING" => "", "SERVER_NAME" => origin.host, "SERVER_PORT" => origin.port.to_s,
+          "rack.url_scheme" => origin.scheme, "rack.input" => StringIO.new(""), "CONTENT_TYPE" => "application/json",
+          "action_dispatch.request.request_parameters" => arguments.deep_stringify_keys,
+          "action_dispatch.request.path_parameters" => route_params.symbolize_keys.merge(controller: klass.controller_path, action: action.to_s) }
+        request = ActionDispatch::Request.new(env)
+        response = ActionDispatch::Response.new
+        _status, _headers, body = klass.new.send(:dispatch_internal, action.to_s, request, response, actor: actor)
+        text = +""
+        body.each { |chunk| text << chunk }
+        text.empty? ? {} : JSON.parse(text)
+      ensure
+        body&.close if body.respond_to?(:close)
+      end
+    end
+  end
+end

data/lib/open_blog/mcp/image_input.rb

@@ -0,0 +1,30 @@
+require "base64"
+require "tempfile"
+
+module OpenBlog
+  module Mcp
+    module ImageInput
+      def self.with_upload(arguments)
+        if arguments.key?(:url)
+          raise Error::ImageNotPermitted unless arguments.keys == [ :url ]
+          return yield(arguments)
+        end
+        encoded = arguments[:base64]
+        maximum = OpenBlog.config.max_image_bytes
+        raise Error::ImageNotPermitted unless encoded.is_a?(String) && encoded.bytesize <= ((maximum + 2) / 3) * 4
+        bytes = Base64.strict_decode64(encoded)
+        raise Error::ImageNotPermitted if bytes.bytesize > maximum
+        filename, content_type = arguments.values_at(:filename, :content_type)
+        raise Error::ImageNotPermitted unless filename.is_a?(String) && filename.present? && content_type.is_a?(String) && content_type.present?
+        Tempfile.create([ "open-blog-upload", ".bin" ], binmode: true) do |file|
+          file.write(bytes)
+          file.rewind
+          upload = ActionDispatch::Http::UploadedFile.new(tempfile: file, filename: filename, type: content_type)
+          yield(file: upload)
+        end
+      rescue ArgumentError
+        raise Error::ImageNotPermitted
+      end
+    end
+  end
+end

data/lib/open_blog/mcp/registry.rb

@@ -0,0 +1,139 @@
+module OpenBlog
+  module Mcp
+    module Registry
+      module_function
+
+      def definitions
+        [
+          endpoint("list_posts", :read, "posts", :index, fields: ApiFields::POST_LIST),
+          endpoint("search_posts", :read, "posts", :index, fields: ApiFields::POST_LIST, required: [ :q ]),
+          endpoint("get_post", :read, "posts", :show, id: :required),
+          endpoint("get_post_records", :read, "records", :show, id: :required),
+          endpoint("check_post", :read, "findings", :show, id: :required),
+          endpoint("save_draft", :write, "posts", :create, fields: ApiFields::POST_WRITE, force: { publish: false }),
+          endpoint("get_preview_link", :read, "previews", :show, id: :required),
+          endpoint("publish_post", :publish, "posts", :publish, fields: ApiFields::POST_WRITE, id: :optional, create_publish: true),
+          endpoint("update_post", :publish, "posts", :update, fields: ApiFields::POST_WRITE, id: :required),
+          endpoint("correct_post", :publish, "posts", :update, fields: ApiFields::POST_WRITE, id: :required, required: [ :note ], force: { change: "correction" }),
+          endpoint("approve_revision", :publish, "approvals", :create, fields: ApiFields::APPROVAL, id: :required, required: ApiFields::APPROVAL),
+          endpoint("declare_connections", :publish, "connections", :create, fields: ApiFields::CONNECTION, id: :required,
+            properties: Schemas.connection_fields, required: %i[connections third_party_paid declared_by]),
+          endpoint("unpublish_post", :publish, "posts", :unpublish, id: :required),
+          endpoint("remove_post", :publish, "posts", :destroy, fields: ApiFields::REMOVE, id: :required),
+          upload_definition,
+          endpoint("list_categories", :read, "categories", :index, fields: ApiFields::PAGE),
+          endpoint("save_category", :write, "categories", :create, fields: ApiFields::CATEGORY, id: :optional, upsert: true),
+          endpoint("list_tags", :read, "tags", :index, fields: ApiFields::PAGE),
+          endpoint("list_authors", :read, "authors", :index, fields: ApiFields::PAGE),
+          endpoint("save_author", :write, "authors", :create, fields: ApiFields::AUTHOR, id: :optional, upsert: true),
+          endpoint("list_series", :read, "series", :index, fields: ApiFields::PAGE),
+          endpoint("save_series", :write, "series", :create, fields: ApiFields::SERIES, id: :optional, upsert: true),
+          endpoint("list_redirects", :read, "redirects", :index, fields: ApiFields::PAGE),
+          endpoint("save_redirect", :publish, "redirects", :create, fields: ApiFields::REDIRECT, required: [ :old_path ]),
+          site_page_definition("get_site_page", :read),
+          site_page_definition("save_site_page", :write),
+          page_views_definition,
+          report_definition,
+          endpoint("doctor", :read, "doctor", :show),
+          endpoint("extract_faq", :read, "faq_extractions", :create, fields: ApiFields::EXTRACTION, required: [ :body ]),
+          endpoint("adopt_post", :publish, "adoptions", :create, fields: ApiFields::ADOPTION,
+            required: %i[source_system source_id slug title body_format body])
+        ]
+      end
+
+      def endpoint(name, scope, controller, action, fields: [], id: nil, required: [], force: {}, upsert: false, create_publish: false, properties: nil)
+        properties ||= Schemas.fields(fields)
+        properties = properties.merge("id" => upsert ? { type: "integer", minimum: 1 } : Schemas.identifier) if id
+        required = required + (id == :required ? [ :id ] : [])
+        force.each { |key, value| properties[key.to_s] = properties.fetch(key.to_s).merge(const: value) if properties.key?(key.to_s) }
+        definition(name, scope, Schemas.object(properties, required: required)) do |arguments, actor:, base_url:|
+          arguments = arguments.dup
+          identity = arguments.delete(:id) if id
+          selected = upsert && identity ? :update : action
+          if create_publish && !identity
+            selected = :create
+            arguments[:publish] = true
+          end
+          arguments.merge!(force)
+          if selected == :index
+            maximum = [ OpenBlog.config.mcp.max_page_size, 100 ].min
+            arguments[:per_page] = [ arguments.fetch(:per_page, 25).to_i, maximum ].min
+          end
+          method = { index: :get, show: :get, update: :patch, destroy: :delete }.fetch(selected, :post)
+          Dispatcher.call(controller: controller, action: selected, method: method, arguments: arguments,
+            actor: actor, route_params: identity ? { id: identity } : {}, base_url: base_url)
+        end
+      end
+
+      def site_page_definition(name, scope)
+        properties = name == "save_site_page" ? Schemas.fields(ApiFields::SITE_PAGE) : {}
+        properties["kind"] = { type: "string", enum: %w[responsible_party corrections editorial ai_use] }
+        if name == "save_site_page"
+          properties["status"] = { type: "string", enum: %w[draft published] }
+          %w[title body slug].each { |field| properties[field] = Schemas.text }
+          %w[approved_by approved_on].each { |field| properties[field] = Schemas.text(nullable: true) }
+        end
+        definition(name, scope, Schemas.object(properties, required: [ :kind ])) do |arguments, actor:, base_url:|
+          input = arguments.dup
+          kind = input.delete(:kind)
+          writing = name == "save_site_page"
+          Dispatcher.call(controller: "pages", action: writing ? :update : :show, method: writing ? :put : :get,
+            arguments: input, actor: actor, route_params: { kind: kind }, base_url: base_url)
+        end
+      end
+
+      def report_definition
+        properties = { "scope" => { type: "string", enum: %w[site post all] }, "post" => Schemas.identifier,
+          "page" => { anyOf: [ { type: "integer", minimum: 1, maximum: 1_000_000 }, { type: "string", pattern: "^[1-9][0-9]*$" } ] },
+          "reach" => { anyOf: [ { type: "boolean" }, { type: "string", enum: %w[true false] } ] } }
+        definition("get_surface_report", :read, Schemas.object(properties)) do |arguments, actor:, base_url:|
+          Dispatcher.call(controller: "report", action: :show, method: :get, arguments: arguments, actor: actor, base_url: base_url)
+        end
+      end
+
+      def page_views_definition
+        properties = { "id" => Schemas.identifier }
+        ApiFields::VIEWS.each { |field| properties[field.to_s] = Schemas.text(nullable: true) }
+        ApiFields::TOP_VIEWS.each do |field|
+          maximum = field == :days ? 36500 : 100
+          properties[field.to_s] = { anyOf: [ { type: "integer", minimum: 1, maximum: maximum }, { type: "string", pattern: "^[1-9][0-9]*$" } ] }
+        end
+        schema = Schemas.object(properties).merge(oneOf: [
+          { required: [ "id" ], not: { anyOf: [ { required: [ "days" ] }, { required: [ "limit" ] } ] } },
+          { not: { anyOf: [ { required: [ "id" ] }, { required: [ "from" ] }, { required: [ "to" ] } ] } }
+        ])
+        definition("get_page_views", :read, schema) do |arguments, actor:, base_url:|
+          input = arguments.dup
+          id = input.delete(:id)
+          Dispatcher.call(controller: "views", action: id ? :show : :top, method: :get, arguments: input,
+            actor: actor, route_params: id ? { post_id: id } : {}, base_url: base_url)
+        end
+      end
+
+      def upload_definition
+        properties = Schemas.fields(%i[url filename content_type]).merge("base64" => Schemas.text)
+        schema = Schemas.object(properties).merge(oneOf: [ { required: [ "url" ], maxProperties: 1 }, { required: %w[base64 filename content_type], maxProperties: 3 } ])
+        definition("upload_image", :write, schema) do |arguments, actor:, base_url:|
+          ImageInput.with_upload(arguments) do |input|
+            Dispatcher.call(controller: "images", action: :create, method: :post, arguments: input, actor: actor, route_params: {}, base_url: base_url)
+          end
+        end
+      end
+
+      def definition(name, scope, schema, &handler)
+        instruction = if name == "adopt_post"
+          OpenBlog::ADOPTION_INSTRUCTION
+        elsif %w[publish_post update_post correct_post approve_revision].include?(name)
+          "#{OpenBlog::APPROVAL_INSTRUCTION} #{OpenBlog::PROVENANCE_INSTRUCTION}"
+        else
+          OpenBlog::APPROVAL_POINTER
+        end
+        instruction += " #{OpenBlog::DRAFT_INSTRUCTION}" if name == "save_draft"
+        description = "#{name.tr('_', ' ').capitalize}. #{instruction}"
+        Definition.new(name: "blog_#{name}", title: name.tr("_", " ").capitalize, description: description,
+          input_schema: schema, annotations: { read_only_hint: scope == :read, destructive_hint: name == "remove_post" },
+          scope: scope, handler: handler)
+      end
+    end
+  end
+end

data/lib/open_blog/mcp/schemas.rb

@@ -0,0 +1,72 @@
+module OpenBlog
+  module Mcp
+    module Schemas
+      module_function
+
+      def object(properties, required: [])
+        { type: "object", properties: properties, required: required.map(&:to_s), additionalProperties: false }
+      end
+
+      def text(nullable: false)
+        { type: nullable ? [ "string", "null" ] : "string" }
+      end
+
+      def identifier
+        { anyOf: [ { type: "integer", minimum: 1 }, { type: "string", minLength: 1 } ] }
+      end
+
+      def fields(names)
+        names.to_h { |name| [ name.to_s, field(name) ] }
+      end
+
+      def field(name)
+        case name.to_sym
+        when :id then identifier
+        when :featured, :facts_checked, :third_party_paid, :dry_run then { type: "boolean" }
+        when :made_by_ai then { type: [ "boolean", "null" ] }
+        when :position then { type: "integer", minimum: -2_147_483_648, maximum: 2_147_483_647 }
+        when :series_position, :post_id then { type: [ "integer", "null" ], minimum: 1 }
+        when :page, :per_page
+          { anyOf: [ { type: "integer", minimum: 1, maximum: 999_999_999 }, { type: "string", pattern: "^[1-9][0-9]{0,8}$" } ] }
+        when :tags, :profile_urls, :standalone_questions then { type: "array", items: text }
+        when :faq then { type: "array", items: object(fields(ApiFields::POST_NESTED.fetch(:faq)), required: %w[question answer]) }
+        when :author
+          { anyOf: [ text, object(fields(ApiFields::POST_NESTED.fetch(:author)), required: [ "name" ]) ] }
+        when :cover_image, :social_image, :avatar
+          { anyOf: [ { type: "null" }, image ] }
+        when :approval
+          object(fields(ApiFields::POST_NESTED.fetch(:approval)), required: %w[name facts_checked])
+        when :connections
+          object(connection_fields, required: %w[connections third_party_paid declared_by])
+        when :declaration
+          object(fields(%i[reviewer_name approved_at facts_checked declared_on declared_by declared_first_published_at]), required: %w[reviewer_name approved_at facts_checked declared_on declared_by])
+        when :imported_approval
+          object(fields(%i[reviewer_name approved_at facts_checked evidence confirmed_by]), required: %w[reviewer_name approved_at facts_checked evidence confirmed_by])
+        when :old_slugs
+          { type: "array", items: { anyOf: [ text, object(fields(%i[slug moved_on]), required: [ "slug" ]) ] } }
+        when :image_id then { type: "integer", minimum: 1 }
+        when :type then { type: "string", enum: %w[person organization] }
+        when :body_format then { type: "string", enum: %w[markdown rich_text] }
+        when :provenance then { type: "string", enum: %w[ai_assisted human_written unknown] }
+        when :change then { type: "string", enum: %w[substantive correction maintenance] }
+        when :status then { type: "string", enum: %w[draft scheduled published archived] }
+        when :body, :description, :search_title, :search_description, :canonical_url, :cover_alt, :external_id,
+            :category, :series, :provenance_evidence, :publish_at, :first_published_at, :last_modified_at,
+            :first_published_evidence, :last_modified_evidence, :declared_first_published_at, :source_body_sha256,
+            :bio, :url, :host_reference, :new_path, :redirect_to, :moved_on
+          text(nullable: true)
+        else text
+        end
+      end
+
+      def connection_fields
+        fields(ApiFields::CONNECTION - [ :connections ]).merge("connections" => { type: "array",
+          items: object(fields(%i[party relation]), required: %w[party relation]) })
+      end
+
+      def image
+        object(fields(%i[image_id signed_id url])).merge(minProperties: 1, maxProperties: 1)
+      end
+    end
+  end
+end

data/lib/open_blog/mcp.rb

@@ -0,0 +1,24 @@
+module OpenBlog
+  module Mcp
+    autoload :Definition, "open_blog/mcp/definition"
+    autoload :Dispatcher, "open_blog/mcp/dispatcher"
+    autoload :Registry, "open_blog/mcp/registry"
+    autoload :Schemas, "open_blog/mcp/schemas"
+    autoload :ImageInput, "open_blog/mcp/image_input"
+
+    def self.definitions
+      Registry.definitions
+    end
+
+    def self.tools
+      definitions.map do |definition|
+        ::MCP::Tool.define(name: definition.name, title: definition.title, description: definition.description,
+          input_schema: definition.input_schema, annotations: definition.annotations) do |server_context: nil, **arguments|
+          result = definition.call(arguments, actor: server_context&.[](:actor), base_url: server_context&.[](:base_url))
+          ::MCP::Tool::Response.new([ { type: "text", text: JSON.generate(result) } ],
+            structured_content: result, error: result.key?("error"))
+        end
+      end
+    end
+  end
+end

data/lib/open_blog/not_found.rb

@@ -0,0 +1,4 @@
+module OpenBlog
+  class NotFound < StandardError
+  end
+end

data/lib/open_blog/operation.rb

@@ -0,0 +1,36 @@
+module OpenBlog
+  class Operation
+    def self.run(post: nil, attributes: {}, actor:, now: Time.current, context: {}, authorize: nil)
+      current = nil
+      result = nil
+      Post.transaction(requires_new: true) do
+        resolved = PostIdentity.resolve(attributes, post: post)
+        current = resolved.persisted? ? Post.lock.find(resolved.id) : resolved
+        authorize&.call(current)
+        created = current.new_record?
+        records = yield(current, created)
+        label = current.destroyed? ? :none : LabelPolicy.for(current)
+        findings = current.destroyed? ? [] : Findings.for(current, context: context)
+        result = Result.new(post: current, created: created, records: records, label: label, findings: findings)
+      end
+      result
+    rescue Error => error
+      failure(current, error)
+    rescue ActiveRecord::RecordInvalid => error
+      collision = error.record.is_a?(Post) && %i[slug external_id].any? do |field|
+        error.record.errors.details[field].any? { |detail| detail[:error] == :taken }
+      end
+      refusal = collision ? Error::IdentityConflict.new : Error::ValidationFailed.new(details: error.record.errors.attribute_names.map(&:to_s))
+      failure(current, refusal)
+    rescue ActiveRecord::RecordNotFound
+      failure(current, Error::NotFound.new)
+    rescue ActiveRecord::RecordNotUnique
+      failure(current, Error::IdentityConflict.new)
+    end
+
+    def self.failure(post, error)
+      post = post.class.find_by(id: post.id) if post&.persisted?
+      Result.new(post: post&.persisted? ? post : nil, error: error)
+    end
+  end
+end

data/lib/open_blog/page_views.rb

@@ -0,0 +1,72 @@
+module OpenBlog
+  module PageViews
+    BOT_PATTERN = /bot|crawler|spider|slurp|preview|monitor|curl|wget|headless|facebookexternalhit|WhatsApp|ChatGPT-User|Claude-User|Perplexity-User|anthropic-ai|cohere-ai|Google-InspectionTool/i
+
+    module_function
+
+    def count!(post, request, now: Time.current)
+      return unless OpenBlog.config.page_views && post.published? && request.get? && request.format.html?
+      return if request.user_agent.blank? || OpenBlog.config.page_view_bot_pattern.match?(request.user_agent)
+      return if request.headers["Sec-Purpose"].to_s.match?(/prefetch/i)
+
+      connection = PageView.connection
+      table = connection.quote_table_name(PageView.table_name)
+      connection.execute("INSERT INTO #{table} (post_id, day, views) VALUES (#{connection.quote(post.id)}, #{connection.quote(now.utc.to_date)}, 1) ON CONFLICT (post_id, day) DO UPDATE SET views = #{table}.views + 1")
+      nil
+    rescue StandardError => error
+      Rails.logger.warn("OpenBlog page view counter failed: #{error.class.name}")
+      nil
+    end
+
+    def for(post, from: nil, to: nil, now: Time.current)
+      to = date(to, :to) || now.utc.to_date
+      from = date(from, :from) || to - 29
+      invalid!(:from) if from > to
+      days = PageView.where(post_id: post.id, day: from..to).order(:day).pluck(:day, :views).map { |day, views| { day: day, views: views } }
+      { post_id: post.id, from: from, to: to, total: days.sum { |row| row[:views] }, days: days }
+    end
+
+    def top(days: 30, limit: 5, base_url: nil, scope: Post.all, now: Time.current)
+      days = positive(days, :days, 36500)
+      limit = positive(limit, :limit, 100)
+      today = now.utc.to_date
+      totals = PageView.where(day: (today - days + 1)..today, post_id: scope.select(:id))
+        .group(:post_id).order(Arel.sql("SUM(views) DESC"), :post_id).limit(limit).pluck(:post_id, Arel.sql("SUM(views)"))
+      posts = Post.where(id: totals.map(&:first)).index_by(&:id)
+      { days: days, posts: totals.filter_map do |id, views|
+        post = posts[id]
+        next unless post
+        { id: id, slug: post.slug, title: post.title, url: post.url(base: OpenBlog.config.public_base_url || base_url), views: views }
+      end }
+    end
+
+    def prune!(now: Time.current)
+      retention = OpenBlog.config.page_view_retention_days
+      return 0 if retention.nil?
+      invalid!(:page_view_retention_days) unless retention.is_a?(Integer) && retention.positive?
+      PageView.where("day < ?", now.utc.to_date - retention).delete_all
+    end
+
+    def date(value, field)
+      return value if value.is_a?(Date)
+      return nil if value.nil?
+      invalid!(field) unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+      Date.iso8601(value)
+    rescue Date::Error
+      invalid!(field)
+    end
+    private_class_method :date
+
+    def positive(value, field, maximum)
+      value = value.to_i if value.is_a?(String) && value.match?(/\A[1-9]\d*\z/)
+      invalid!(field) unless value.is_a?(Integer) && value.between?(1, maximum)
+      value
+    end
+    private_class_method :positive
+
+    def invalid!(field)
+      raise Error::ValidationFailed.new(details: [ field.to_s ])
+    end
+    private_class_method :invalid!
+  end
+end

data/lib/open_blog/pagination.rb

@@ -0,0 +1,18 @@
+module OpenBlog
+  class Pagination
+    Page = Data.define(:records, :page, :total_pages)
+
+    def self.page(scope, page:, per_page:)
+      value = page.nil? ? 1 : page
+      unless value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A[1-9]\d*\z/))
+        raise NotFound
+      end
+      number = value.to_i
+      raise NotFound unless number.positive? && per_page.is_a?(Integer) && per_page.positive?
+      count = scope.reorder(nil).count
+      total = [ (count.to_f / per_page).ceil, 1 ].max
+      raise NotFound if number > total
+      Page.new(records: scope.offset((number - 1) * per_page).limit(per_page).to_a, page: number, total_pages: total)
+    end
+  end
+end

data/lib/open_blog/plain_text.rb

@@ -0,0 +1,36 @@
+require "commonmarker"
+require "nokogiri"
+
+module OpenBlog
+  module PlainText
+    class << self
+      def from_markdown(text)
+        text_from_node(Commonmarker.parse(text.to_s.encode(Encoding::UTF_8))).strip
+      end
+
+      def from_html(html)
+        Nokogiri::HTML.fragment(html.to_s).text
+      end
+
+      private
+
+      def text_from_node(node)
+        case node.type
+        when :text, :code
+          node.literal
+        when :code_block
+          "#{node.literal.sub(/\n+\z/, "")}\n"
+        when :html_inline
+          from_html(node.literal)
+        when :html_block
+          "#{from_html(node.literal)}\n"
+        when :softbreak, :linebreak, :thematic_break
+          "\n"
+        else
+          text = node.each.map { |child| text_from_node(child) }.join
+          %i[paragraph heading table_row].include?(node.type) ? "#{text}\n" : text
+        end
+      end
+    end
+  end
+end

data/lib/open_blog/policy_url.rb

@@ -0,0 +1,9 @@
+module OpenBlog
+  class PolicyUrl
+    def self.call(kind, config: OpenBlog.config)
+      kind = kind.to_s
+      return unless Page::KINDS.include?(kind)
+      config.policy_urls[kind.to_sym].presence || Page.published.find_by(kind: kind)&.path
+    end
+  end
+end