og_pilot_ruby 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c76008dde8c56d665a3eece4869fa7f28ec0ad656ef2cae798da373956d055
-  data.tar.gz: 1a2e055c83968ed81d0ca747457403c865c045d37acd5694f9ac5fc221497d57
+  metadata.gz: b3a7a8cb4b3b8346a2fc20b5f2fff70122dfc7fefb95513a196c8408aeec566c
+  data.tar.gz: 7c2f0a25126d3c5c03c4471d3a6c7f1dc76012b9187074bbb0caa2381361bdc0
 SHA512:
-  metadata.gz: efb3af2ede82a7519c855dfd6e9bbbfc17940a22ce91a12f3bac1e3e63e65fba92e61b9554ba8e5f2a39cc47a2557ef215595b4776d71dbef1c232333cc5d16b
-  data.tar.gz: e3f0bc81c47bfce15490c8348c0db2a32c601b6761200dd25487baf0294799890ebb5b7d864ebf44ea800f5d3a2f9393b433a19f8c8a0df117c2ed3d8a934dc2
+  metadata.gz: 51438c44674e1cf92fc0e4d1ea75ea932a98f2ad9a68ec02d13b71edc89d02a53cf7eaf07a2d8a4e433a7fc3efaa43400943f989401f67d9a23e5f514b2148b9
+  data.tar.gz: cfed717cb42d3a00eecdbe1d745559d2ecbacd25296753ca7c82594e2c765ac299441a37705daf027dec9c920a41bed18ceaf60c3ab7ea53352a0d36d4794ed0

data/README.md

@@ -60,6 +60,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`.

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.0"
 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.0
 platform: ruby
 authors:
 - Sunergos IT LLC