og_pilot_ruby 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14139a28eb73f49d006b651becb58d4068c0988b53dc60d824fcb63ce5cdf1b
-  data.tar.gz: a39dabc07a52b76c5cff89bd822f8303a2d744701c1223c788917e878fae8487
+  metadata.gz: 34c76008dde8c56d665a3eece4869fa7f28ec0ad656ef2cae798da373956d055
+  data.tar.gz: 1a2e055c83968ed81d0ca747457403c865c045d37acd5694f9ac5fc221497d57
 SHA512:
-  metadata.gz: bd80040f049488ed5052b20dd2ff71d6c099b47d69eabfd626544a8230dadd139a7c976ab256ee474f8d1f1ab1a5f1364b83954a2995d0d2f574200802f1222c
-  data.tar.gz: 324610fd591ff18eb0c9be51f538e4fdd8325ed28572909afde1fb2ce2cc51edc33622828505e8f30ad46f25b623cfadc1de87a5f1deba79ae579589c2645493
+  metadata.gz: efb3af2ede82a7519c855dfd6e9bbbfc17940a22ce91a12f3bac1e3e63e65fba92e61b9554ba8e5f2a39cc47a2557ef215595b4776d71dbef1c232333cc5d16b
+  data.tar.gz: e3f0bc81c47bfce15490c8348c0db2a32c601b6761200dd25487baf0294799890ebb5b7d864ebf44ea800f5d3a2f9393b433a19f8c8a0df117c2ed3d8a934dc2

data/README.md

@@ -1,5 +1,8 @@
 # OG Pilot Ruby
 
+> [!IMPORTANT]  
+> An active [OG Pilot](https://ogpilot.com?ref=og_pilot_ruby) subscription is required to use this gem.
+
 A small Ruby client for generating OG Pilot Open Graph images via signed JWTs.
 
 ## Installation
@@ -57,6 +60,78 @@ image_url = OgPilotRuby.create_image(
 If you omit `iat`, OG Pilot will cache the image indefinitely. Provide an `iat` to
 refresh the cache daily.
 
+## Parameters
+
+All parameters are embedded in the signed JWT payload; the only query param is `token`.
+The gem handles `iss` (domain) and `sub` (API key prefix) automatically.
+
+### Core parameters
+
+| Parameter     | Required | Default  | Description                                                   |
+|---------------|----------|----------|---------------------------------------------------------------|
+| `template`    | No       | `"page"` | Template name                                                 |
+| `title`       | Yes      | —        | Primary title text                                            |
+| `description` | No       | —        | Subtitle or supporting text                                   |
+| `logo_url`    | No       | —        | Logo image URL                                                |
+| `image_url`   | No       | —        | Hero image URL                                                |
+| `bg_color`    | No       | —        | Background color (hex format)                                 |
+| `text_color`  | No       | —        | Text color (hex format)                                       |
+| `iat`         | No       | —        | Issued-at timestamp for daily cache busting                   |
+| `path`        | No       | auto-set | Request path for image rendering context. When provided, it overrides auto-resolution (see [Path handling](#path-handling)) |
+
+### Ruby options
+
+| Option    | Default | Description                                                              |
+|-----------|---------|--------------------------------------------------------------------------|
+| `json`    | `false` | When `true`, sends `Accept: application/json` and parses the JSON response |
+| `headers` | —       | Additional HTTP headers to include with the request                      |
+| `default` | `false` | Forces `path` to `/` when `true`, unless a manual `path` is provided (see [Path handling](#path-handling)) |
+
+### Template-specific parameters
+
+| Template    | Parameters                                                                         |
+|-------------|------------------------------------------------------------------------------------|
+| `page`      | `title`, `description`                                                             |
+| `blog_post` | `title`, `author_name`, `author_avatar_url`, `publish_date` (ISO 8601)             |
+| `podcast`   | `title`, `episode_date` (ISO 8601)                                                 |
+| `product`   | `title`, `unique_selling_point`                                                    |
+| `event`     | `title`, `event_date`, `event_location`                                            |
+| `book`      | `title`, `description`, `book_author`, `book_series_number`, `book_description`, `book_genre` |
+| `portfolio` | `title`                                                                            |
+| `company`   | `title`, `company_logo_url`, `description` (note: `image_url` is ignored)          |
+
+### Path handling
+
+The `path` parameter enhances OG Pilot analytics by tracking which OG images perform better across different pages on your site. Without it, all analytics would be aggregated under the `/` path, making it difficult to understand how individual pages or content types are performing. By automatically capturing the request path, you get granular insights into click-through rates and engagement for each OG image.
+
+The client automatically injects a `path` parameter on every request:
+
+| Option           | Behavior                                                                                                                                                               |
+|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `default: false` | Uses the current request path when available. In Rails, prefers `request.fullpath` (via the per-request store), then falls back to Rack/CGI env vars (`REQUEST_URI`, `PATH_INFO`). If no path can be determined, uses `/`. |
+| `default: true`  | Forces the `path` parameter to `/`, regardless of the current request (unless `path` is provided explicitly).                                                           |
+| `path: "/..."`   | Uses the provided path verbatim (normalized to start with `/`), overriding auto-resolution.                                                                             |
+
+**Example:**
+
+```ruby
+image_url = OgPilotRuby.create_image(
+  template: "blog_post",
+  title: "How to Build Amazing OG Images",
+  default: true
+)
+```
+
+Manual override:
+
+```ruby
+image_url = OgPilotRuby.create_image(
+  template: "page",
+  title: "Hello OG Pilot",
+  path: "/pricing?plan=pro"
+)
+```
+
 Fetch JSON metadata instead:
 
 ```ruby

data/lib/og_pilot_ruby/client.rb

@@ -15,7 +15,14 @@ module OgPilotRuby
       @config = config
     end
 
-    def create_image(params = {}, json: false, iat: nil, headers: {})
+    def create_image(params = {}, json: false, iat: nil, headers: {}, default: false)
+      params ||= {}
+      params = params.dup
+      # Always include a path; manual overrides win, otherwise resolve from the current request.
+      manual_path = params.key?(:path) ? params[:path] : params["path"]
+      params.delete("path") if params.key?("path")
+      params[:path] = manual_path.to_s.strip.empty? ? resolved_path(default:) : normalize_path(manual_path)
+
       uri = build_uri(params, iat:)
       response = request(uri, json:, headers:)
 
@@ -96,5 +103,79 @@ module OgPilotRuby
       def api_key_prefix
         api_key!.slice(0, 8)
       end
+
+      # Rails-first path resolution with Rack/CGI env fallback.
+      def resolved_path(default:)
+        return "/" if default
+
+        path = rails_fullpath
+        path = env_fullpath if path.nil? || path.empty?
+        normalize_path(path)
+      end
+
+      def rails_fullpath
+        return unless defined?(::Rails)
+
+        request = rails_request_from_store || rails_request_from_thread
+        fullpath = request.fullpath if request&.respond_to?(:fullpath)
+        fullpath unless fullpath.nil? || fullpath.empty?
+      end
+
+      def rails_request_from_store
+        return unless defined?(::RequestStore) && ::RequestStore.respond_to?(:store)
+
+        store = ::RequestStore.store
+        store[:action_dispatch_request] ||
+          store[:"action_dispatch.request"] ||
+          store[:request]
+      end
+
+      def rails_request_from_thread
+        Thread.current[:og_pilot_request] ||
+          Thread.current[:action_dispatch_request] ||
+          Thread.current[:"action_dispatch.request"] ||
+          Thread.current[:request]
+      end
+
+      def env_fullpath
+        request_uri = ENV["REQUEST_URI"]
+        return request_uri unless request_uri.nil? || request_uri.empty?
+
+        original_fullpath = ENV["ORIGINAL_FULLPATH"]
+        return original_fullpath unless original_fullpath.nil? || original_fullpath.empty?
+
+        path_info = ENV["PATH_INFO"]
+        return build_fullpath_from_path_info(path_info) unless path_info.nil? || path_info.empty?
+
+        request_path = ENV["REQUEST_PATH"]
+        return request_path unless request_path.nil? || request_path.empty?
+
+        nil
+      end
+
+      def build_fullpath_from_path_info(path_info)
+        query = ENV["QUERY_STRING"].to_s
+        return path_info if query.empty?
+
+        "#{path_info}?#{query}"
+      end
+
+      def normalize_path(path)
+        cleaned = path.to_s.strip
+        return "/" if cleaned.empty?
+
+        cleaned = extract_request_uri(cleaned)
+        cleaned = "/#{cleaned}" unless cleaned.start_with?("/")
+        cleaned
+      end
+
+      def extract_request_uri(value)
+        return value unless value.start_with?("http://", "https://")
+
+        uri = URI.parse(value)
+        uri.request_uri || "/"
+      rescue URI::InvalidURIError
+        value
+      end
   end
 end

data/lib/og_pilot_ruby/rails_helper.rb

@@ -2,8 +2,8 @@
 
 module OgPilotRuby
   module RailsHelper
-    def create_image(params = {}, json: false, iat: nil, headers: {}, **keyword_params)
-      OgPilotRuby.create_image(params, json:, iat:, headers:, **keyword_params)
+    def create_image(params = {}, json: false, iat: nil, headers: {}, default: false, **keyword_params)
+      OgPilotRuby.create_image(params, json:, iat:, headers:, default:, **keyword_params)
     end
   end
 end

data/lib/og_pilot_ruby/railtie.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 if defined?(Rails::Railtie)
+  require_relative "request_store_middleware"
+
   module OgPilotRuby
     # Rails integration for OG Pilot Ruby
     class Railtie < Rails::Railtie
@@ -9,6 +11,10 @@ if defined?(Rails::Railtie)
           inflect.acronym 'OgPilotRuby'
         end
       end
+
+      initializer 'og_pilot_ruby.middleware' do |app|
+        app.middleware.use OgPilotRuby::RequestStoreMiddleware
+      end
     end
   end
 end

data/lib/og_pilot_ruby/request_store_middleware.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OgPilotRuby
+  # Middleware that stores the current request in Thread.current
+  # so OgPilotRuby::Client can access it for path resolution.
+  class RequestStoreMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      Thread.current[:og_pilot_request] = request
+      @app.call(env)
+    ensure
+      Thread.current[:og_pilot_request] = nil
+    end
+  end
+end

data/lib/og_pilot_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OgPilotRuby
-  VERSION = "0.1.3"
+  VERSION = "0.2.1"
 end

data/lib/og_pilot_ruby.rb

@@ -25,9 +25,9 @@ module OgPilotRuby
       Client.new(config)
     end
 
-    def create_image(params = {}, json: false, iat: nil, headers: {}, **keyword_params)
+    def create_image(params = {}, json: false, iat: nil, headers: {}, default: false, **keyword_params)
       params ||= {}
-      client.create_image(params.merge(keyword_params), json:, iat:, headers:)
+      client.create_image(params.merge(keyword_params), json:, iat:, headers:, default:)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: og_pilot_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.1
 platform: ruby
 authors:
 - Sunergos IT LLC
@@ -72,6 +72,7 @@ files:
 - lib/og_pilot_ruby/jwt_encoder.rb
 - lib/og_pilot_ruby/rails_helper.rb
 - lib/og_pilot_ruby/railtie.rb
+- lib/og_pilot_ruby/request_store_middleware.rb
 - lib/og_pilot_ruby/version.rb
 homepage: https://ogpilot.com
 licenses: