og_pilot_ruby 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e2a983c2b0ced955a1d89e715316050384d6879ec31e328b391e1b7d6e788e9
-  data.tar.gz: a2e254954c6f260f493f10e86fd19b8a7d2a64781f9a970ad730bd51fc411962
+  metadata.gz: ee4898069ea1b40ff62e9db35ca4d5c726aaa27cf7b658c233c9f5f9bcc70bb2
+  data.tar.gz: 4c38cee9d0e4753208e3b65c37c4b33a6b478fa1b34c9fd16cd98aca56836c56
 SHA512:
-  metadata.gz: 8fe9e289d37a64f41c9d578aba09477ce5e0fa9ea29a422ded261b9ab01b45c02cb7aff88581ed446bd2e5aafeb94c9f49b5762e374bfe6b63d6063985ec462b
-  data.tar.gz: 96d7f35d05dae228f048bae8e7ee55a046fc4480f2546b5153c3bf72763ccd7116efa41d59c6b9f71b9d651cd0d17aca71636dfaba6a62123d8a71a2c8257ef3
+  metadata.gz: 2c1772c79ca7847a027611e42869888017b53e2e829a1262c519fb708d7e30e9fd4bce3bb0eb1ccc997c022a250b314ceadc88d3db5bcdb6c415c6aa23d5a177
+  data.tar.gz: dced72f71149af6c1544bd11ff0803e10159d81e1f0039a58df025009e8527f7b4a1f4eca2bfe934d86e8d37f47a353bf9c6dfb1e32b4ba387d1ed8f4b01a66a

data/README.md

@@ -29,6 +29,8 @@ OgPilotRuby.configure do |config|
   config.api_key = ENV.fetch("OG_PILOT_API_KEY")
   config.domain = ENV.fetch("OG_PILOT_DOMAIN")
   # config.strip_extensions = true
+  # config.cache_store = Rails.cache
+  # config.cache_ttl = 86_400
 end
 ```
 
@@ -61,6 +63,12 @@ image_url = OgPilotRuby.create_image(
 If you omit `iat`, OG Pilot will cache the image indefinitely. Provide an `iat` to
 refresh the cache daily.
 
+When `config.cache_store` is set, the client can also cache generated responses
+locally:
+
+- With `iat`: cache for `cache_ttl` seconds
+- Without `iat`: cache for `7 * cache_ttl` seconds
+
 ### Fail-safe behavior
 
 `create_image` is non-blocking. If any error occurs (request, configuration,
@@ -558,6 +566,9 @@ The gem handles `iss` (domain) and `sub` (API key prefix) automatically.
 | `open_timeout`     | `5`                     | Connection timeout in seconds                                            |
 | `read_timeout`     | `10`                    | Read timeout in seconds                                                  |
 | `strip_extensions` | `true`                  | When `true`, file extensions are stripped from resolved paths (see [Strip extensions](#strip-extensions)) |
+| `strip_query_parameters` | `false`           | When `true`, query strings are removed from resolved paths before signing (see [Strip query parameters](#strip-query-parameters)) |
+| `cache_store`      | `nil`                   | Optional cache backend with `read`/`write` (for example `Rails.cache`)  |
+| `cache_ttl`        | `86400`                 | Cache TTL in seconds when `cache_store` is enabled                       |
 
 ### Ruby options
 
@@ -624,6 +635,26 @@ payload = {
 data = OgPilotRuby.create_image(**payload, json: true)
 ```
 
+### Local caching
+
+You can optionally enable client-side caching to avoid repeated API calls for
+identical payloads:
+
+```ruby
+OgPilotRuby.configure do |config|
+  config.cache_store = Rails.cache
+  config.cache_ttl = 86_400 # 1 day
+end
+```
+
+Cache key inputs include the normalized payload, `iat`, output mode (`json`
+vs URL), and configured domain.
+
+TTL behavior:
+
+- If `iat` is present: cached for `cache_ttl`
+- If `iat` is omitted: cached for `7 * cache_ttl`
+
 ### Strip extensions
 
 When `strip_extensions` is enabled, the client removes file extensions from the
@@ -649,6 +680,25 @@ OgPilotRuby.create_image(title: "Docs", path: "/docs.php")
 # Dotfiles are unchanged: /.hidden stays /.hidden
 ```
 
+### Strip query parameters
+
+When `strip_query_parameters` is enabled, the client drops the query string from
+every resolved path before it signs the payload. This keeps analytics grouped
+under the canonical path even when links include tracking or pagination
+parameters. It works alongside `strip_extensions`, so
+`/archive.tar.gz?ref=campaign` resolves to `"/archive"` when both are enabled.
+
+```ruby
+OgPilotRuby.configure do |config|
+  config.strip_query_parameters = true
+end
+
+# These resolve to "/docs":
+OgPilotRuby.create_image(title: "Docs", path: "/docs")
+OgPilotRuby.create_image(title: "Docs", path: "/docs?ref=main")
+OgPilotRuby.create_image(title: "Docs", path: "https://example.com/docs?ref=campaign")
+```
+
 ## Development
 
 Run tests with:

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

@@ -9,4 +9,5 @@ OgPilotRuby.configure do |config|
   # config.open_timeout = 5
   # config.read_timeout = 10
   # config.strip_extensions = true
+  # config.strip_query_parameters = true
 end

data/lib/og_pilot_ruby/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "logger"
 require "net/http"
@@ -25,14 +26,24 @@ module OgPilotRuby
       params.delete("path") if params.key?("path")
       params[:path] = manual_path.to_s.strip.empty? ? resolved_path(default:) : normalize_path(manual_path)
 
+      cache_key = cache_key_for(params, iat:, json:)
+      if config.cache_store && cache_key
+        cached = read_cached(cache_key)
+        return cached if cached
+      end
+
       uri = build_uri(params, iat:)
       response, final_uri = request(uri, json:, headers:)
 
-      if json
+      result = if json
         JSON.parse(response.body)
       else
         response["Location"] || final_uri.to_s
       end
+
+      write_cached(cache_key, result, iat:) if config.cache_store && cache_key && result
+
+      result
     rescue StandardError => e
       log_create_image_failure(e, json:)
       json ? { "image_url" => nil } : nil
@@ -42,6 +53,25 @@ module OgPilotRuby
 
       attr_reader :config
 
+      def cache_key_for(params, iat:, json:)
+        key_data = params.transform_keys(&:to_sym).merge(iat: iat, json: json, domain: domain!)
+        normalized = key_data.sort_by { |k, _| k.to_s }.to_h
+        "og_pilot:#{Digest::SHA256.hexdigest(normalized.to_json)[0, 16]}"
+      end
+
+      def read_cached(cache_key)
+        config.cache_store.read(cache_key)
+      rescue StandardError
+        nil
+      end
+
+      def write_cached(cache_key, result, iat:)
+        ttl = iat ? config.cache_ttl : (7 * config.cache_ttl)
+        config.cache_store.write(cache_key, result, expires_in: ttl)
+      rescue StandardError
+        nil
+      end
+
       def log_create_image_failure(error, json:)
         mode = json ? "json" : "url"
         message = "OgPilotRuby create_image failed (mode=#{mode}): #{error.class}: #{error.message}"
@@ -223,6 +253,7 @@ module OgPilotRuby
         cleaned = extract_request_uri(cleaned)
         cleaned = "/#{cleaned}" unless cleaned.start_with?("/")
         cleaned = strip_extension(cleaned) if config.strip_extensions
+        cleaned = remove_query_parameters(cleaned) if config.strip_query_parameters
         cleaned
       end
 
@@ -248,6 +279,11 @@ module OgPilotRuby
         query ? "#{stripped}?#{query}" : stripped
       end
 
+      def remove_query_parameters(path)
+        stripped = path.split("?", 2).first
+        stripped.empty? ? "/" : stripped
+      end
+
       def extract_request_uri(value)
         return value unless value.start_with?("http://", "https://")
 

data/lib/og_pilot_ruby/configuration.rb

@@ -5,7 +5,7 @@ module OgPilotRuby
     DEFAULT_BASE_URL = "https://ogpilot.com"
     private_constant :DEFAULT_BASE_URL
 
-    attr_accessor :api_key, :domain, :base_url, :open_timeout, :read_timeout, :strip_extensions
+    attr_accessor :api_key, :domain, :base_url, :open_timeout, :read_timeout, :strip_extensions, :strip_query_parameters, :cache_store, :cache_ttl
 
     def initialize
       @api_key = ENV.fetch("OG_PILOT_API_KEY", nil)
@@ -14,6 +14,9 @@ module OgPilotRuby
       @open_timeout = 5
       @read_timeout = 10
       @strip_extensions = true
+      @strip_query_parameters = false
+      @cache_store = nil
+      @cache_ttl = 86400
     end
   end
 end

data/lib/og_pilot_ruby/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: og_pilot_ruby
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Sunergos IT LLC
@@ -97,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Ruby client for the OG Pilot Open Graph image generator.
 test_files: []