og_pilot_ruby 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dd502b31b2e2a9128c20c39cd1a42c78e265591084e4ad372fa9155077d2b5f
-  data.tar.gz: 2a22d99307f56fa8e3e069c2b04b6692f44e845d7fee146f0aa5ab416cfb0e46
+  metadata.gz: 5a03463da25a6c59b2ee3813ae94141cf23e49949268711c211fc68da2b4c1ed
+  data.tar.gz: f126ee78f60803700f0c751c2098c50a3e992a88f15d9616f32c1dfb17b9477d
 SHA512:
-  metadata.gz: 9125aaf624243e7ff5ac70a9170e2a0c5e0cd676c756cb3aeae0f793be57e1f44f120d7d9b05b0e60514d074e452475e2f443f0a7944d49f19cfab2150bd0a38
-  data.tar.gz: b8486e526ff135fd80023a35f9b4ab9a44c446198303a8e70d227a4babee40b108c2a589136ba3871e185f76c0730f7ca240341a9837d285ae9ab18d4ea4f665
+  metadata.gz: e1c29c159b7e3ae1cc9556f9444cada0af6b42e5b27a520b386da978eae1b7666a7ccd0dd50bbe1bd0c9e03d7f34d52387c7ea7f957e10c8927d3aa9f58cc7e3
+  data.tar.gz: 7e4efd68d6b7c56294e064fc0e2b73d9acd9911f66db8805886e427469f08c2823f35524c16d091ad3cd36ebc8630ef9ef445a6a90adc85332e9c1e7fdfa43a2

data/README.md

@@ -57,6 +57,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

@@ -4,7 +4,7 @@ require "json"
 require "net/http"
 require "uri"
 
-require_relative "errors"
+require_relative "error"
 require_relative "jwt_encoder"
 
 module OgPilotRuby
@@ -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.2"
+  VERSION = "0.2.0"
 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.2
+  version: 0.2.0
 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: