opengraphplus 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d947ee47bc0e434395f69cceb99321f78ab4f8ac437f5b537b97ffa9a199d51
-  data.tar.gz: 308d3466e160b11f935afd3b9f0c891ba3b268f95f3de12400af9e815020a82f
+  metadata.gz: 76feb6f71feac815baf6dc136ba5653801e84048adb3ca77d9dffe59d76004be
+  data.tar.gz: a7177af1e7c9f4ec5844ddc66602c75420b07c15a9f3b266e772bfdd093984f6
 SHA512:
-  metadata.gz: ac3f345867d3cc9e5ad6fa1745f5f6ea45cf505fdd057191c0af0d48ca62d8af6e64aa7dfa26b2097f8d97af95fab8dec9888a37b00a573bc94c5ad68660c6c3
-  data.tar.gz: 9a20a378f2e36d594667c2abdba8e194bdcae2bc55a2daf33bf1195162b9c9498ca257e426e645ae85a3087cc0f80b83ff9f7065f730cc240564daf7617e58e7
+  metadata.gz: 7b8be6792864e32d690507fc03afb246e4a0ffa5ddf0caf75289352a9b54070d2de89845ea0236edad762c562174fa68c4b46ebc567d71fa8a223726a9a7af06
+  data.tar.gz: 678c88ffc101a8720d29c8dbbc6156f16adf8fb2a28c263b8f025fd431dc61da4167bc5719aa533a87a66412fcff37d26944f9e80c94623f1e48bb4249431efd

data/README.md

@@ -18,7 +18,161 @@ gem install opengraphplus
 
 ## Usage
 
-When this gem is complete, an API key will be required to connect to the gem, the it's installed, added to a layout, and it should just work.
+### Get your API key
+
+Sign up at [og.plus](https://og.plus) to get your API key.
+
+### Configuration
+
+#### Using environment variables
+
+```bash
+rails g opengraphplus:env ogp_live_████████████████████
+```
+
+This will:
+- Append `OPENGRAPHPLUS__API_KEY=ogp_live_████████████████████` to your `.env` file (or the first env file found)
+- Create `config/initializers/opengraphplus.rb`
+
+To specify a different env file:
+
+```bash
+rails g opengraphplus:env ogp_live_████████████████████ -e .envrc
+```
+
+#### Using Rails credentials
+
+```bash
+rails g opengraphplus:credentials ogp_live_████████████████████
+```
+
+This will:
+- Add `opengraphplus.api_key` to your encrypted `credentials.yml.enc`
+- Create `config/initializers/opengraphplus.rb`
+
+#### Manual configuration
+
+Run the basic install generator for a commented template:
+
+```bash
+rails g opengraphplus:install
+```
+
+Then configure manually in `config/initializers/opengraphplus.rb`:
+
+```ruby
+OpenGraphPlus.configure do |config|
+  config.api_key = ENV["OPENGRAPHPLUS__API_KEY"]
+  # or
+  config.api_key = Rails.application.credentials.opengraphplus.api_key
+end
+```
+
+## Verifying OpenGraph Tags
+
+You can verify that your pages have the required OpenGraph tags using the included command:
+
+```bash
+rails opengraph:verify http://localhost:3000
+```
+
+This will fetch the URL and check for required tags (`og:title`, `og:type`, `og:image`, `og:url`), displaying any missing required or recommended tags:
+
+```
+Verifying OpenGraph tags at http://localhost:3000...
+
+Found tags:
+  og:title       → "My Awesome Site"
+  og:type        → "website"
+  og:image       → "https://example.com/image.png"
+  og:url         → "http://localhost:3000"
+
+✓ All required OpenGraph tags present
+```
+
+The command exits with code 0 on success, or 1 if required tags are missing.
+
+## Testing
+
+OpenGraphPlus provides test helpers for both RSpec and Minitest to verify OpenGraph tags in your test suite.
+
+### RSpec
+
+Add to your `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require 'opengraphplus/rspec'
+```
+
+Then use the matchers in your specs:
+
+```ruby
+RSpec.describe "Home page", type: :request do
+  it "has all required OpenGraph tags" do
+    get "/"
+    expect(response.body).to have_open_graph_tags
+  end
+
+  it "has the correct title" do
+    get "/"
+    expect(response.body).to have_og_tag("og:title").with_content("My Site")
+  end
+
+  it "has an og:image tag" do
+    get "/"
+    expect(response.body).to have_og_tag("og:image")
+  end
+end
+```
+
+Available matchers:
+- `have_open_graph_tags` - Passes if all required OG tags are present
+- `have_og_tag("og:title")` - Passes if the specified tag exists
+- `have_og_tag("og:title").with_content("My Title")` - Passes if the tag has the expected content
+
+### Minitest
+
+Add to your test helper:
+
+```ruby
+require 'opengraphplus/minitest'
+
+class ActiveSupport::TestCase
+  include OpenGraphPlus::Minitest
+end
+```
+
+Then use the assertions in your tests:
+
+```ruby
+class HomePageTest < ActionDispatch::IntegrationTest
+  test "has all required OpenGraph tags" do
+    get "/"
+    assert_open_graph_tags(response.body)
+  end
+
+  test "has the correct title" do
+    get "/"
+    assert_og_tag(response.body, "og:title", "My Site")
+  end
+
+  test "has an og:image tag" do
+    get "/"
+    assert_og_tag(response.body, "og:image")
+  end
+
+  test "does not have private tags" do
+    get "/"
+    refute_og_tag(response.body, "og:private")
+  end
+end
+```
+
+Available assertions:
+- `assert_open_graph_tags(html)` - Passes if all required OG tags are present
+- `assert_og_tag(html, "og:title")` - Passes if the specified tag exists
+- `assert_og_tag(html, "og:title", "My Title")` - Passes if the tag has the expected content
+- `refute_og_tag(html, "og:private")` - Passes if the specified tag does not exist
 
 ## Development
 

data/lib/generators/opengraphplus/base_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Opengraphplus
+  module Generators
+    class BaseGenerator < Rails::Generators::Base
+      API_KEY_PREFIX = "ogp_"
+
+      argument :api_key, type: :string, required: true,
+        desc: "Your OpenGraphPlus API key"
+
+      def validate_api_key
+        unless api_key.start_with?(API_KEY_PREFIX)
+          say_status :error, "Invalid API key: must start with '#{API_KEY_PREFIX}'", :red
+          raise SystemExit
+        end
+      end
+    end
+  end
+end

data/lib/generators/opengraphplus/credentials/credentials_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "active_support/core_ext/hash/keys"
+require_relative "../base_generator"
+
+module Opengraphplus
+  module Generators
+    class CredentialsGenerator < BaseGenerator
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Configures OpenGraphPlus using Rails encrypted credentials"
+
+      def add_to_credentials
+        credentials = Rails.application.credentials
+
+        unless credentials.key?
+          say_status :error, "No credentials key found. Run `rails credentials:edit` first.", :red
+          return
+        end
+
+        # Read existing content, merge, write back
+        yaml_content = credentials.read.presence || ""
+        config = parse_yaml(yaml_content)
+
+        config["opengraphplus"] ||= {}
+        config["opengraphplus"]["api_key"] = api_key
+
+        credentials.write(yaml_dump(config))
+        say_status :insert, "credentials.yml.enc (opengraphplus.api_key)", :green
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/opengraphplus.rb"
+      end
+
+      private
+
+      def parse_yaml(content)
+        return {} if content.blank?
+        YAML.safe_load(content, permitted_classes: [Symbol], aliases: true) || {}
+      end
+
+      def yaml_dump(config)
+        # Preserve nice formatting
+        YAML.dump(config.deep_stringify_keys)
+      end
+    end
+  end
+end

data/lib/generators/opengraphplus/credentials/templates/initializer.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+OpenGraphPlus.configure do |config|
+  config.api_key = Rails.application.credentials.opengraphplus.api_key
+end

data/lib/generators/opengraphplus/env/env_generator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../base_generator"
+
+module Opengraphplus
+  module Generators
+    class EnvGenerator < BaseGenerator
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Configures OpenGraphPlus using environment variables"
+
+      class_option :envfile, type: :string, aliases: "-e",
+        desc: "Specific env file to write to (e.g., .env, .envrc)"
+
+      ENV_FILES = %w[.env .env.local .env.development .env.development.local .envrc].freeze
+      ENV_VAR_NAME = "OPENGRAPHPLUS__API_KEY"
+
+      def append_to_env_file
+        if options[:envfile]
+          write_to_env_file(options[:envfile], create: true)
+        else
+          env_file = detect_env_file
+          if env_file
+            write_to_env_file(env_file)
+          else
+            say_status :skip, "No env file found (create one or use -e)", :yellow
+          end
+        end
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/opengraphplus.rb"
+      end
+
+      private
+
+      def detect_env_file
+        ENV_FILES.find { |f| File.exist?(f) }
+      end
+
+      def write_to_env_file(env_file, create: false)
+        env_line = "#{ENV_VAR_NAME}=#{api_key}"
+
+        unless File.exist?(env_file)
+          if create
+            create_file env_file, "#{env_line}\n"
+          end
+          return
+        end
+
+        if File.read(env_file).include?(ENV_VAR_NAME)
+          say_status :skip, "#{env_file} (#{ENV_VAR_NAME} already defined)", :yellow
+        else
+          content = File.read(env_file)
+          prefix = content.end_with?("\n") || content.empty? ? "" : "\n"
+          append_to_file env_file, "#{prefix}#{env_line}\n"
+        end
+      end
+    end
+  end
+end

data/lib/generators/opengraphplus/env/templates/initializer.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+OpenGraphPlus.configure do |config|
+  config.api_key = ENV["OPENGRAPHPLUS__API_KEY"]
+end

data/lib/generators/opengraphplus/install/templates/README

@@ -1,46 +1,6 @@
 
 OpenGraphPlus has been installed!
 
-Next steps:
-
-1. Add your API key to config/initializers/opengraphplus.rb
-   Get your API key at: https://opengraphplus.com/dashboard
-
-2. Add the helper to your layout file (e.g., app/views/layouts/application.html.erb):
-
-   <head>
-     <%%= open_graph_meta_tags %>
-   </head>
-
-3. Customize the default Open Graph tags in ApplicationController:
-
-   class ApplicationController < ActionController::Base
-     open_graph do |og|
-       og.type = "website"
-       og.url = request.original_url
-       og.site_name = "Your Site Name"
-     end
-   end
-
-4. Override tags in specific controllers (inherits from parent):
-
-   class ArticlesController < ApplicationController
-     before_action { @article = Article.find(params[:id]) }
-
-     open_graph do |og|
-       og.title = @article.title
-       og.description = @article.excerpt
-       og.type = "article"
-     end
-   end
-
-5. Set tags in views:
-
-   <%% open_graph do |og|
-     og.title = "My Page Title"
-     og.description = "My Page Description"
-   end %>
-
-6. Verify it works by checking your page source for og:image meta tags,
-   or use the preview tool at: https://opengraphplus.com/previews/new
+For setup instructions, visit https://opengraphplus.com/guides/rails
 
+For a website API key, visit https://opengraphplus.com/dashboard

data/lib/generators/opengraphplus/install/templates/initializer.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+# Get your API key at https://opengraphplus.com/dashboard
 OpenGraphPlus.configure do |config|
-  # Get your API key at https://opengraphplus.com/dashboard
+  # Use Rails credentials.
   config.api_key = Rails.application.credentials.opengraphplus_api_key
+
   # Or use ENV:
   # config.api_key = ENV["OPENGRAPHPLUS_API_KEY"]
 end

data/lib/opengraphplus/minitest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "opengraphplus"
+
+module OpenGraphPlus
+  module Minitest
+    # Assert that all required OpenGraph tags are present
+    #
+    # @param html [String] The HTML to check
+    # @param message [String, nil] Custom failure message
+    #
+    # @example
+    #   assert_open_graph_tags(response.body)
+    #
+    def assert_open_graph_tags(html, message = nil)
+      parser = OpenGraphPlus::Parser.new(html)
+      message ||= "Expected HTML to have all required OpenGraph tags, but missing: #{parser.errors.join(', ')}"
+      assert parser.valid?, message
+    end
+
+    # Assert that a specific OpenGraph/Twitter tag is present
+    #
+    # @param html [String] The HTML to check
+    # @param property [String] The tag property (e.g., "og:title")
+    # @param content [String, nil] Expected content (optional)
+    # @param message [String, nil] Custom failure message
+    #
+    # @example
+    #   assert_og_tag(response.body, "og:title")
+    #   assert_og_tag(response.body, "og:title", "My Title")
+    #
+    def assert_og_tag(html, property, content = nil, message = nil)
+      parser = OpenGraphPlus::Parser.new(html)
+      actual_content = parser[property]
+
+      if content.nil?
+        message ||= "Expected HTML to have #{property} tag, but it was not found"
+        assert !actual_content.nil?, message
+      else
+        message ||= "Expected #{property} to have content #{content.inspect}, but got #{actual_content.inspect}"
+        assert_equal content, actual_content, message
+      end
+    end
+
+    # Assert that a specific OpenGraph/Twitter tag is NOT present
+    #
+    # @param html [String] The HTML to check
+    # @param property [String] The tag property (e.g., "og:title")
+    # @param message [String, nil] Custom failure message
+    #
+    # @example
+    #   refute_og_tag(response.body, "og:private")
+    #
+    def refute_og_tag(html, property, message = nil)
+      parser = OpenGraphPlus::Parser.new(html)
+      actual_content = parser[property]
+      message ||= "Expected HTML not to have #{property} tag, but it was found with content #{actual_content.inspect}"
+      assert actual_content.nil?, message
+    end
+  end
+end

data/lib/opengraphplus/parser.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module OpenGraphPlus
+  class Parser
+    REQUIRED_TAGS = %w[og:title og:type og:image og:url].freeze
+    RECOMMENDED_TAGS = %w[og:description og:site_name twitter:card twitter:title twitter:image].freeze
+
+    attr_reader :html
+
+    def initialize(html)
+      @html = html.to_s
+      @tags = parse_meta_tags
+    end
+
+    def og_tags
+      @tags.select { |key, _| key.start_with?("og:") }
+    end
+
+    def twitter_tags
+      @tags.select { |key, _| key.start_with?("twitter:") }
+    end
+
+    def all_tags
+      @tags.dup
+    end
+
+    def [](property)
+      @tags[property]
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def errors
+      REQUIRED_TAGS.reject { |tag| @tags.key?(tag) }
+    end
+
+    def warnings
+      RECOMMENDED_TAGS.reject { |tag| @tags.key?(tag) }
+    end
+
+    private
+
+    def parse_meta_tags
+      doc = Nokogiri::HTML(@html)
+      tags = {}
+
+      doc.css("meta[property^='og:'], meta[name^='og:']").each do |meta|
+        property = meta["property"] || meta["name"]
+        content = meta["content"]
+        tags[property] = content if property && content
+      end
+
+      doc.css("meta[property^='twitter:'], meta[name^='twitter:']").each do |meta|
+        property = meta["property"] || meta["name"]
+        content = meta["content"]
+        tags[property] = content if property && content
+      end
+
+      tags
+    end
+  end
+end

data/lib/opengraphplus/rspec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "opengraphplus"
+require "rspec/expectations"
+
+module OpenGraphPlus
+  module RSpec
+    extend ::RSpec::Matchers::DSL
+
+    # Matches if all required OpenGraph tags are present
+    #
+    # @example
+    #   expect(response.body).to have_open_graph_tags
+    #
+    matcher :have_open_graph_tags do
+      match do |html|
+        @parser = OpenGraphPlus::Parser.new(html)
+        @parser.valid?
+      end
+
+      failure_message do
+        "expected HTML to have all required OpenGraph tags, but missing: #{@parser.errors.join(', ')}"
+      end
+
+      failure_message_when_negated do
+        "expected HTML not to have all required OpenGraph tags, but all were present"
+      end
+    end
+
+    # Matches if a specific OpenGraph/Twitter tag is present
+    #
+    # @example
+    #   expect(response.body).to have_og_tag("og:title")
+    #   expect(response.body).to have_og_tag("og:title").with_content("My Title")
+    #
+    matcher :have_og_tag do |property|
+      chain :with_content do |expected_content|
+        @expected_content = expected_content
+      end
+
+      match do |html|
+        @parser = OpenGraphPlus::Parser.new(html)
+        @actual_content = @parser[property]
+
+        if @actual_content.nil?
+          false
+        elsif @expected_content
+          @actual_content == @expected_content
+        else
+          true
+        end
+      end
+
+      failure_message do
+        if @actual_content.nil?
+          "expected HTML to have #{property} tag, but it was not found"
+        else
+          "expected #{property} to have content #{@expected_content.inspect}, but got #{@actual_content.inspect}"
+        end
+      end
+
+      failure_message_when_negated do
+        if @expected_content
+          "expected #{property} not to have content #{@expected_content.inspect}, but it did"
+        else
+          "expected HTML not to have #{property} tag, but it was found with content #{@actual_content.inspect}"
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include OpenGraphPlus::RSpec
+end

data/lib/opengraphplus/verifier.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module OpenGraphPlus
+  class Verifier
+    class FetchError < Error; end
+
+    MAX_REDIRECTS = 5
+
+    attr_reader :url
+
+    def initialize(url)
+      @url = url
+    end
+
+    def verify
+      html = fetch_html
+      Parser.new(html)
+    end
+
+    private
+
+    def fetch_html(redirect_count = 0)
+      raise FetchError, "Too many redirects" if redirect_count > MAX_REDIRECTS
+
+      uri = URI.parse(@url)
+      response = Net::HTTP.get_response(uri)
+
+      case response
+      when Net::HTTPSuccess
+        response.body
+      when Net::HTTPRedirection
+        @url = response["location"]
+        fetch_html(redirect_count + 1)
+      else
+        raise FetchError, "HTTP #{response.code}: #{response.message}"
+      end
+    rescue URI::InvalidURIError => e
+      raise FetchError, "Invalid URL: #{e.message}"
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
+      raise FetchError, "Connection failed: #{e.message}"
+    end
+  end
+end

data/lib/opengraphplus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenGraphPlus
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

data/lib/opengraphplus.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "opengraphplus/version"
+
+module OpenGraphPlus
+  class Error < StandardError; end
+end
+
 require_relative "opengraphplus/api_key"
 require_relative "opengraphplus/configuration"
 require_relative "opengraphplus/signature"
 require_relative "opengraphplus/tag"
 require_relative "opengraphplus/namespace"
 require_relative "opengraphplus/image_generator"
-
-module OpenGraphPlus
-  class Error < StandardError; end
-end
+require_relative "opengraphplus/parser"
+require_relative "opengraphplus/verifier"
 
 require_relative "opengraphplus/rails" if defined?(::Rails::Railtie)

data/lib/rails/commands/opengraph/opengraph_command.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rails/command"
+
+module Rails
+  module Command
+    class OpengraphCommand < Base
+      namespace "opengraph"
+
+      desc "verify URL", "Verify OpenGraph tags at a URL"
+      def verify(url)
+        require "opengraphplus"
+
+        say "Verifying OpenGraph tags at #{url}..."
+        say ""
+
+        begin
+          parser = OpenGraphPlus::Verifier.new(url).verify
+        rescue OpenGraphPlus::Verifier::FetchError => e
+          say_error e.message
+          exit 1
+        end
+
+        tags = parser.all_tags
+
+        if tags.any?
+          say "Found tags:"
+          max_key_length = tags.keys.map(&:length).max
+          tags.each do |property, content|
+            say "  #{property.ljust(max_key_length)} → #{content.inspect}"
+          end
+          say ""
+        else
+          say "No OpenGraph or Twitter tags found."
+          say ""
+        end
+
+        if parser.errors.any?
+          say "Missing required tags:"
+          parser.errors.each do |tag|
+            say "  ✗ #{tag}"
+          end
+          say ""
+        end
+
+        if parser.warnings.any?
+          say "Missing recommended tags:"
+          parser.warnings.each do |tag|
+            say "  - #{tag}"
+          end
+          say ""
+        end
+
+        if parser.valid?
+          say "✓ All required OpenGraph tags present"
+        else
+          say "Verification failed: #{parser.errors.length} required tag(s) missing"
+          exit 1
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: opengraphplus
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Brad Gessler
 bindir: exe
 cert_chain: []
-date: 2026-01-07 00:00:00.000000000 Z
+date: 2026-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -34,6 +34,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/generators/opengraphplus/base_generator.rb
+- lib/generators/opengraphplus/credentials/credentials_generator.rb
+- lib/generators/opengraphplus/credentials/templates/initializer.rb.tt
+- lib/generators/opengraphplus/env/env_generator.rb
+- lib/generators/opengraphplus/env/templates/initializer.rb.tt
 - lib/generators/opengraphplus/install/install_generator.rb
 - lib/generators/opengraphplus/install/templates/README
 - lib/generators/opengraphplus/install/templates/initializer.rb
@@ -42,7 +47,9 @@ files:
 - lib/opengraphplus/api_key.rb
 - lib/opengraphplus/configuration.rb
 - lib/opengraphplus/image_generator.rb
+- lib/opengraphplus/minitest.rb
 - lib/opengraphplus/namespace.rb
+- lib/opengraphplus/parser.rb
 - lib/opengraphplus/rails.rb
 - lib/opengraphplus/rails/controller.rb
 - lib/opengraphplus/rails/helper.rb
@@ -50,13 +57,16 @@ files:
 - lib/opengraphplus/rails/signature.rb
 - lib/opengraphplus/rails/signature/routes.rb
 - lib/opengraphplus/rails/signature/scope.rb
+- lib/opengraphplus/rspec.rb
 - lib/opengraphplus/signature.rb
 - lib/opengraphplus/signature/generator.rb
 - lib/opengraphplus/signature/url.rb
 - lib/opengraphplus/signature/verifier.rb
 - lib/opengraphplus/tag.rb
 - lib/opengraphplus/tags.rb
+- lib/opengraphplus/verifier.rb
 - lib/opengraphplus/version.rb
+- lib/rails/commands/opengraph/opengraph_command.rb
 - sig/open_graph_plus.rbs
 homepage: https://opengraphplus.com/ruby
 licenses: