og_pilot_ruby 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c76008dde8c56d665a3eece4869fa7f28ec0ad656ef2cae798da373956d055
-  data.tar.gz: 1a2e055c83968ed81d0ca747457403c865c045d37acd5694f9ac5fc221497d57
+  metadata.gz: 9624035f48941775c8b1e55637f9d20e6c65a10ffdcfe983ab47ef2ae53dae5d
+  data.tar.gz: 4889190ff785ff95df863f3e320fa17c04f08e1ae2f9772ffa405922440ec58f
 SHA512:
-  metadata.gz: efb3af2ede82a7519c855dfd6e9bbbfc17940a22ce91a12f3bac1e3e63e65fba92e61b9554ba8e5f2a39cc47a2557ef215595b4776d71dbef1c232333cc5d16b
-  data.tar.gz: e3f0bc81c47bfce15490c8348c0db2a32c601b6761200dd25487baf0294799890ebb5b7d864ebf44ea800f5d3a2f9393b433a19f8c8a0df117c2ed3d8a934dc2
+  metadata.gz: 8e43e439eea7e9a8684c77cbc591a94dabc41b40b4096b8ea06eba2a8a73cb680868f362360ede49242285e94902b0258439bf40c47ae5ca91206098c74eb6b6
+  data.tar.gz: 5b966815886946cf1af21c2028a1e9a0721a8c820df34557e8bdd047fc457fe7650b8b4848a5438ecf56dbb8cb0653519bdcf6b8a2999800ab29e9f4f2071a99

data/README.md

@@ -28,6 +28,7 @@ Override as needed:
 OgPilotRuby.configure do |config|
   config.api_key = ENV.fetch("OG_PILOT_API_KEY")
   config.domain = ENV.fetch("OG_PILOT_DOMAIN")
+  # config.strip_extensions = true
 end
 ```
 
@@ -60,6 +61,30 @@ image_url = OgPilotRuby.create_image(
 If you omit `iat`, OG Pilot will cache the image indefinitely. Provide an `iat` to
 refresh the cache daily.
 
+### Template helpers
+
+`create_image` defaults to the `page` template when `template` is omitted.
+
+Use these helpers to force a specific template:
+
+- `OgPilotRuby.create_blog_post_image(...)`
+- `OgPilotRuby.create_podcast_image(...)`
+- `OgPilotRuby.create_product_image(...)`
+- `OgPilotRuby.create_event_image(...)`
+- `OgPilotRuby.create_book_image(...)`
+- `OgPilotRuby.create_company_image(...)`
+- `OgPilotRuby.create_portfolio_image(...)`
+
+Example:
+
+```ruby
+image_url = OgPilotRuby.create_blog_post_image(
+  title: "How to Build Amazing OG Images",
+  author_name: "Jane Smith",
+  publish_date: "2024-01-15"
+)
+```
+
 ## Parameters
 
 All parameters are embedded in the signed JWT payload; the only query param is `token`.
@@ -79,6 +104,17 @@ The gem handles `iss` (domain) and `sub` (API key prefix) automatically.
 | `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)) |
 
+### Configuration options
+
+| Option             | Default                 | Description                                                              |
+|--------------------|-------------------------|--------------------------------------------------------------------------|
+| `api_key`          | `ENV["OG_PILOT_API_KEY"]` | Your OG Pilot API key                                                   |
+| `domain`           | `ENV["OG_PILOT_DOMAIN"]`  | Your domain registered with OG Pilot                                    |
+| `base_url`         | `https://ogpilot.com`   | OG Pilot API base URL                                                    |
+| `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)) |
+
 ### Ruby options
 
 | Option    | Default | Description                                                              |
@@ -137,12 +173,37 @@ Fetch JSON metadata instead:
 ```ruby
 payload = {
   template: "page",
-  title: "Hello OG Pilot"
+  title: "Hello OG Pilot"q
 }
 
 data = OgPilotRuby.create_image(**payload, json: true)
 ```
 
+### Strip extensions
+
+When `strip_extensions` is enabled, the client removes file extensions from the
+last segment of every resolved path. This ensures that `/docs`, `/docs.md`,
+`/docs.php`, and `/docs.html` all resolve to `"/docs"`, so analytics are
+consolidated under a single path regardless of the URL extension.
+
+Multiple extensions are also stripped (`/archive.tar.gz` becomes `/archive`).
+Dotfiles like `/.hidden` are left unchanged. Query strings are preserved.
+
+```ruby
+OgPilotRuby.configure do |config|›
+  config.strip_extensions = true
+end
+
+# All of these resolve to path "/docs":
+OgPilotRuby.create_image(title: "Docs", path: "/docs")
+OgPilotRuby.create_image(title: "Docs", path: "/docs.md")
+OgPilotRuby.create_image(title: "Docs", path: "/docs.php")
+
+# Nested paths work too: /blog/my-post.html → /blog/my-post
+# Query strings are preserved: /docs.md?ref=main → /docs?ref=main
+# Dotfiles are unchanged: /.hidden stays /.hidden
+```
+
 ## Development
 
 Run tests with:

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

@@ -8,4 +8,5 @@ OgPilotRuby.configure do |config|
   # Optional overrides:
   # config.open_timeout = 5
   # config.read_timeout = 10
+  # config.strip_extensions = true
 end

data/lib/og_pilot_ruby/client.rb

@@ -166,9 +166,32 @@ module OgPilotRuby
 
         cleaned = extract_request_uri(cleaned)
         cleaned = "/#{cleaned}" unless cleaned.start_with?("/")
+        cleaned = strip_extension(cleaned) if config.strip_extensions
         cleaned
       end
 
+      def strip_extension(path)
+        path_part, query = path.split("?", 2)
+
+        dir = File.dirname(path_part)
+        base = File.basename(path_part)
+
+        # Don't strip dotfiles like "/.hidden" or "/.env" — only strip when
+        # there's a non-dot character before the first meaningful dot.
+        unless base.match?(/\A\./)  # starts with dot = hidden file, skip
+          base = base.sub(/\..+\z/, "")
+        end
+
+        stripped = if dir == "/" || dir == "."
+                     "/#{base}"
+                   else
+                     "#{dir}/#{base}"
+                   end
+        stripped = "/" if stripped.empty?
+
+        query ? "#{stripped}?#{query}" : 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
+    attr_accessor :api_key, :domain, :base_url, :open_timeout, :read_timeout, :strip_extensions
 
     def initialize
       @api_key = ENV.fetch("OG_PILOT_API_KEY", nil)
@@ -13,6 +13,7 @@ module OgPilotRuby
       @base_url = DEFAULT_BASE_URL
       @open_timeout = 5
       @read_timeout = 10
+      @strip_extensions = true
     end
   end
 end

data/lib/og_pilot_ruby/rails_helper.rb

@@ -1,9 +1,59 @@
 # frozen_string_literal: true
 
 module OgPilotRuby
+  # View-helper mix-in for Rails controllers and views.
+  #
+  # Include this module to access all +OgPilotRuby+ image-generation methods
+  # as instance methods. Every call is forwarded to the corresponding
+  # module-level method, so configuration and client behaviour remain
+  # identical.
+  #
+  # @example In a Rails controller or view
+  #   class PagesController < ApplicationController
+  #     helper OgPilotRuby::RailsHelper
+  #   end
+  #
+  #   # In a view:
+  #   <%= tag.meta property: "og:image", content: create_image(title: "Hello") %>
   module RailsHelper
-    def create_image(params = {}, json: false, iat: nil, headers: {}, default: false, **keyword_params)
-      OgPilotRuby.create_image(params, json:, iat:, headers:, default:, **keyword_params)
+    # @see OgPilotRuby.create_image
+    def create_image(**options)
+      OgPilotRuby.create_image(**options)
+    end
+
+    # @see OgPilotRuby.create_blog_post_image
+    def create_blog_post_image(**options)
+      OgPilotRuby.create_blog_post_image(**options)
+    end
+
+    # @see OgPilotRuby.create_podcast_image
+    def create_podcast_image(**options)
+      OgPilotRuby.create_podcast_image(**options)
+    end
+
+    # @see OgPilotRuby.create_product_image
+    def create_product_image(**options)
+      OgPilotRuby.create_product_image(**options)
+    end
+
+    # @see OgPilotRuby.create_event_image
+    def create_event_image(**options)
+      OgPilotRuby.create_event_image(**options)
+    end
+
+    # @see OgPilotRuby.create_book_image
+    def create_book_image(**options)
+      OgPilotRuby.create_book_image(**options)
+    end
+
+    # @see OgPilotRuby.create_company_image
+    def create_company_image(**options)
+      OgPilotRuby.create_company_image(**options)
+    end
+
+    # @see OgPilotRuby.create_portfolio_image
+    def create_portfolio_image(**options)
+      OgPilotRuby.create_portfolio_image(**options)
     end
   end
 end

data/lib/og_pilot_ruby/version.rb

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

data/lib/og_pilot_ruby.rb

@@ -9,26 +9,265 @@ loader.setup
 
 module OgPilotRuby
   class << self
+    # Returns the current {Configuration} instance, initializing one with
+    # defaults when accessed for the first time.
+    #
+    # @return [OgPilotRuby::Configuration]
     def config
       @config ||= Configuration.new
     end
 
+    # Yields the current {Configuration} for block-style setup.
+    #
+    # @yieldparam config [OgPilotRuby::Configuration]
+    # @return [void]
+    #
+    # @example
+    #   OgPilotRuby.configure do |config|
+    #     config.api_key = ENV.fetch("OG_PILOT_API_KEY")
+    #     config.domain  = ENV.fetch("OG_PILOT_DOMAIN")
+    #   end
     def configure
       yield config
     end
 
+    # Resets the configuration to a fresh {Configuration} instance.
+    # Primarily useful in tests.
+    #
+    # @return [OgPilotRuby::Configuration]
     def reset_config!
       @config = Configuration.new
     end
 
+    # Returns a new {Client} instance wired to the current configuration.
+    #
+    # @return [OgPilotRuby::Client]
     def client
       Client.new(config)
     end
 
-    def create_image(params = {}, json: false, iat: nil, headers: {}, default: false, **keyword_params)
-      params ||= {}
-      client.create_image(params.merge(keyword_params), json:, iat:, headers:, default:)
+    # Generates an Open Graph image URL via OG Pilot.
+    #
+    # All image parameters and request options are passed as keyword arguments.
+    # Defaults to the +page+ template when +template+ is omitted.
+    #
+    # == Core parameters
+    #   template    - String template name (default: +"page"+).
+    #   title       - String primary title text (*required*).
+    #   description - String subtitle or supporting text.
+    #   logo_url    - String logo image URL.
+    #   image_url   - String hero image URL.
+    #   bg_color    - String background color (hex format).
+    #   text_color  - String text color (hex format).
+    #   path        - String request path for analytics context.
+    #
+    # == Request options
+    #   iat     - Integer issued-at timestamp for daily cache busting.
+    #   json    - Boolean when +true+, returns parsed JSON metadata
+    #             instead of an image URL (default: +false+).
+    #   headers - Hash of additional HTTP headers to include.
+    #   default - Boolean forces +path+ to +"/"+ when +true+
+    #             (default: +false+).
+    #
+    # @param options [Hash] keyword arguments containing image parameters
+    #   and request options.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example Generate an image URL
+    #   OgPilotRuby.create_image(
+    #     template: "blog_post",
+    #     title:    "How to Build Amazing OG Images",
+    #     iat:      Time.now.to_i
+    #   )
+    #
+    # @example Fetch JSON metadata
+    #   OgPilotRuby.create_image(title: "Hello OG Pilot", json: true)
+    def create_image(**options)
+      request_opts = extract_request_options!(options)
+      client.create_image(options, **request_opts)
     end
+
+    # Generates an Open Graph image using the +blog_post+ template.
+    #
+    # == Template parameters
+    #   title             - String primary title text (*required*).
+    #   author_name       - String author display name.
+    #   author_avatar_url - String author avatar image URL.
+    #   publish_date      - String publication date (ISO 8601).
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_blog_post_image(
+    #     title:        "How to Build Amazing OG Images",
+    #     author_name:  "Jane Smith",
+    #     publish_date: "2024-01-15"
+    #   )
+    def create_blog_post_image(**options)
+      create_image(**options.merge(template: "blog_post"))
+    end
+
+    # Generates an Open Graph image using the +podcast+ template.
+    #
+    # == Template parameters
+    #   title        - String primary title text (*required*).
+    #   episode_date - String episode date (ISO 8601).
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_podcast_image(
+    #     title:        "The Future of Ruby",
+    #     episode_date: "2024-03-01"
+    #   )
+    def create_podcast_image(**options)
+      create_image(**options.merge(template: "podcast"))
+    end
+
+    # Generates an Open Graph image using the +product+ template.
+    #
+    # == Template parameters
+    #   title                - String primary title text (*required*).
+    #   unique_selling_point - String product USP.
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_product_image(
+    #     title:                "Wireless Headphones",
+    #     unique_selling_point: "50-hour battery life"
+    #   )
+    def create_product_image(**options)
+      create_image(**options.merge(template: "product"))
+    end
+
+    # Generates an Open Graph image using the +event+ template.
+    #
+    # == Template parameters
+    #   title          - String primary title text (*required*).
+    #   event_date     - String event date.
+    #   event_location - String event location.
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_event_image(
+    #     title:          "RubyConf 2024",
+    #     event_date:     "2024-11-13",
+    #     event_location: "Chicago, IL"
+    #   )
+    def create_event_image(**options)
+      create_image(**options.merge(template: "event"))
+    end
+
+    # Generates an Open Graph image using the +book+ template.
+    #
+    # == Template parameters
+    #   title              - String primary title text (*required*).
+    #   description        - String subtitle or supporting text.
+    #   book_author        - String book author name.
+    #   book_series_number - String or Integer series number.
+    #   book_description   - String book description.
+    #   book_genre         - String book genre.
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_book_image(
+    #     title:       "The Ruby Way",
+    #     book_author: "Hal Fulton",
+    #     book_genre:  "Programming"
+    #   )
+    def create_book_image(**options)
+      create_image(**options.merge(template: "book"))
+    end
+
+    # Generates an Open Graph image using the +company+ template.
+    #
+    # == Template parameters
+    #   title            - String primary title text (*required*).
+    #   description      - String company description.
+    #   company_logo_url - String company logo image URL.
+    #
+    # Note: +image_url+ is ignored for this template.
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_company_image(
+    #     title:            "Acme Corp",
+    #     description:      "Building the future",
+    #     company_logo_url: "https://example.com/logo.png"
+    #   )
+    def create_company_image(**options)
+      create_image(**options.merge(template: "company"))
+    end
+
+    # Generates an Open Graph image using the +portfolio+ template.
+    #
+    # == Template parameters
+    #   title - String primary title text (*required*).
+    #
+    # Accepts all core parameters and request options documented on
+    # {.create_image}.
+    #
+    # @param options [Hash] keyword arguments.
+    # @return [String] the resolved image URL when +json+ is +false+.
+    # @return [Hash]   the parsed JSON response when +json+ is +true+.
+    #
+    # @example
+    #   OgPilotRuby.create_portfolio_image(title: "My Portfolio")
+    def create_portfolio_image(**options)
+      create_image(**options.merge(template: "portfolio"))
+    end
+
+    private
+
+      # Extracts Ruby-specific request options from +options+, mutating the
+      # hash in place so that only image parameters remain.
+      #
+      # @param options [Hash] the full keyword arguments hash (modified in place).
+      # @return [Hash] a keyword hash (+json+, +iat+, +headers+, +default+)
+      #   compatible with {Client#create_image}.
+      def extract_request_options!(options)
+        {
+          json:    options.delete(:json) || false,
+          iat:     options.delete(:iat),
+          headers: options.delete(:headers) || {},
+          default: options.delete(:default) || false
+        }
+      end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: og_pilot_ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Sunergos IT LLC