bannerbear 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2da12377f479bda2685084b6de8bbaedd54b043f565e2b8d646ff9d36c1ec93
-  data.tar.gz: 477db9f95c4df6f068667816546d813e4021288301103a207c61e6227aa199d6
+  metadata.gz: 850108dc51b0e1e90d1e7e6452ce69b65c972638e33d7f6b946f0f81ab4fe1cd
+  data.tar.gz: f4c1e8883281527d9c515a07d358a251629ec19fb06a2dab4506fb95cfd9576a
 SHA512:
-  metadata.gz: 619e0c3e44fd9be99a86d0874418d6f4d6db14bf94c6200f3decb78a83f0fd7cb8e02ced1f86bd3d562a53d617e7e98f99165ce4372d5a49bafdaf4f55b411d8
-  data.tar.gz: 64d0ed8cec035ce84a9976915515ab63106e0e9ed8e890b37887b57e41cc68401877e877a228e0cae7e6c594da4319cd5fc72a44c0390046cbab37a162ddd8e3
+  metadata.gz: de72ce94b734dbcfc73ca872ce5b2ce9f41c23b6f5c1bf40e2cf78bf8e2938b81933ab20113c41b5e8ad0af2dc034ff251b696ef310219063ea066dfdbf759ba
+  data.tar.gz: 92bfc10f330f5d318084b8e446491678029de74807ef353e2d679279590e22487780e15f4b093fa0bf374c8601fc6e685faf8d9d96f9fa4266f088638080186f

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/smoke_test_v5.rb

data/Gemfile.lock

@@ -1,19 +1,21 @@
 PATH
   remote: .
   specs:
-    bannerbear (0.1.2)
+    bannerbear (0.2.0)
       httparty
 
 GEM
   remote: https://rubygems.org/
   specs:
-    httparty (0.20.0)
-      mime-types (~> 3.0)
+    bigdecimal (4.1.2)
+    csv (3.3.5)
+    httparty (0.24.2)
+      csv
+      mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
-    mime-types (3.4.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2021.1115)
-    multi_xml (0.6.0)
+    mini_mime (1.1.5)
+    multi_xml (0.9.1)
+      bigdecimal (>= 3.1, < 5)
     rake (12.3.3)
 
 PLATFORMS

data/README.md

@@ -1,4 +1,4 @@
-# Bannerbear
+# Bannerbear Ruby
 
 Ruby wrapper for the [Bannerbear API](https://developers.bannerbear.com) - an image and video generation service.
 
@@ -18,6 +18,228 @@ Or install it yourself as:
 
     $ gem install bannerbear
 
+## V5 API
+
+The [V5 API](https://developers.bannerbear.com/v5/) is a new generation of the Bannerbear API. **V5 API keys do not work with V2 endpoints, and V2 API keys do not work with V5 endpoints** — you must use the right client class for your key.
+
+For the **V5 API**, use `Bannerbear::V5::Client` (this section).
+For the **legacy V2 API**, see [Usage](#usage) below — that section is unchanged.
+
+### Table of Contents
+
+- [Authentication (V5)](#authentication-v5)
+- [Account (V5)](#account-v5)
+- [Image Templates (V5)](#image-templates-v5)
+- [Images (V5)](#images-v5)
+- [Batches (V5)](#batches-v5)
+- [Webhooks (V5)](#webhooks-v5)
+- [Instant URLs (V5)](#instant-urls-v5)
+
+### Authentication (V5)
+
+```ruby
+bb = Bannerbear::V5::Client.new("your V5 API key")
+```
+
+Or set `BANNERBEAR_API_KEY` and call without arguments:
+
+```ruby
+bb = Bannerbear::V5::Client.new
+```
+
+### Account (V5)
+
+```ruby
+bb.account
+```
+
+### Image Templates (V5)
+
+V5 renames V2's `templates` resource to `image_templates`.
+
+```ruby
+bb.list_image_templates(page: 1)
+bb.get_image_template("template uid")
+bb.update_image_template("template uid", name: "New Name", description: "...", tags: ["portrait"])
+```
+
+### Images (V5)
+
+V5's `modifications` is an **object** with two sub-keys:
+
+- `template` — template-level changes (width, height, etc.)
+- `objects` — array of per-layer changes (equivalent to V2's flat modifications array)
+
+```ruby
+bb.create_image("template uid",
+  modifications: {
+    template: { width: 1080, height: 1080 },
+    objects:  [
+      { name: "headline", text: "Hello World!" },
+      { name: "photo",    image_url: "https://images.unsplash.com/photo-1555400038-63f5ba517a47?w=1000&q=80" }
+    ]
+  }
+)
+```
+
+Synchronous generation routes to `sync.api.bannerbear.com/v5` (10s timeout). The `sync:` flag is a Ruby-level switch — it is **not** sent in the request body:
+
+```ruby
+bb.create_image("template uid", sync: true, modifications: { objects: [...] })
+```
+
+##### Options for `create_image`
+
+- `modifications`: V5 modifications object (`hash`)
+- `formats`: output formats, e.g. `["jpg", "pdf"]` (`array`)
+- `scale`: scale multiplier, 1–4 (`integer`)
+- `dpi`: DPI metadata (`integer`)
+- `quality`: quality control (`integer`)
+- `proxy`: proxy server for asset fetching (`string`)
+- `metadata`: include any metadata to reference at a later point (`string`)
+- `version`: pin template version (`integer`)
+- `sync`: route to the sync host (`boolean`; Ruby-only, not sent to the API)
+
+```ruby
+bb.get_image("image uid")
+bb.list_images(page: 1)
+```
+
+### Batches (V5)
+
+Generate multiple images in one request (up to 100).
+
+```ruby
+bb.create_batch(
+  type:  "image",
+  items: [
+    { template: "template uid 1", modifications: { objects: [...] } },
+    { template: "template uid 2", modifications: { objects: [...] } }
+  ]
+)
+bb.get_batch("batch uid")
+bb.list_batches(page: 1)
+```
+
+### Webhooks (V5)
+
+Webhooks are managed as a first-class resource in V5 (instead of being a per-request `webhook_url` parameter).
+
+```ruby
+hook = bb.create_webhook(
+  name:      "my-webhook",
+  url:       "https://example.com/hook",
+  resource:  "image",
+  event:     "completed",
+  status:    "active",
+  scope:     "all",
+  templates: []
+)
+
+# IMPORTANT: signing_key is ONLY returned in the create response. Store it now —
+# subsequent get_webhook calls will not include it.
+puts hook["signing_key"]
+```
+
+CRUD:
+
+```ruby
+bb.get_webhook("webhook uid")
+bb.update_webhook("webhook uid",
+  name:     "renamed",
+  url:      "https://example.com/hook",
+  resource: "image",
+  event:    "completed",
+  status:   "active",
+  scope:    "all"
+)
+bb.delete_webhook("webhook uid")
+bb.list_webhooks(page: 1)
+```
+
+### Instant URLs (V5)
+
+Instant URLs are URLs bound to a template that can be manipulated with query strings — the V5 equivalent of V2's "Signed URLs" feature.
+
+#### Create an Instant URL base
+
+```ruby
+iurl = bb.create_instant_url(
+  name:     "my-instant-url",
+  template: "template uid",
+  mode:     "encoded",      # or "named_params"
+  security: "signed",       # or "open"
+  status:   "active",
+  scale:    1               # 1, 2, 3, or 4
+)
+
+# IMPORTANT: signing_key is ONLY returned in the create response. Store it now.
+puts iurl["signing_key"]
+puts iurl["base_url"]
+```
+
+##### Options for `create_instant_url` / `update_instant_url`
+
+- `name` *required* (`string`)
+- `template` *required* — image template UID (`string`)
+- `mode`: `"encoded"` or `"named_params"` (`string`)
+- `security`: `"signed"` or `"open"` (`string`)
+- `status`: `"active"` or `"disabled"` (`string`)
+- `scale`: 1, 2, 3, or 4 (`integer`)
+- `rate_limit`: enable per-IP rate limiting (`boolean`)
+- `template_version`: pin template version (`integer`, nullable)
+- `max_renders`: cap total renders (`integer`, nullable)
+- `expires_at`: ISO 8601 expiry (`string`, nullable)
+
+CRUD:
+
+```ruby
+bb.get_instant_url("uid")
+bb.update_instant_url("uid", name: "...", template: "...", ...)
+bb.delete_instant_url("uid")
+bb.list_instant_urls(page: 1)
+```
+
+#### Build an Instant URL with modifications
+
+`build_instant_url` is a pure local helper — no API call. It composes the URL from a base + modifications and, if a signing key is provided, appends the HMAC signature.
+
+```ruby
+# Encoded mode, signed
+bb.build_instant_url(iurl["base_url"],
+  mode:        "encoded",
+  signing_key: iurl["signing_key"],
+  modifications: {
+    template: { width: 1030, height: 890 },
+    objects:  [{ name: "title", text: "Hello!", color: "#ffffff" }]
+  }
+)
+
+# Named params mode, signed
+bb.build_instant_url(iurl["base_url"],
+  mode:        "named_params",
+  signing_key: iurl["signing_key"],
+  modifications: {
+    template: { width: 1030, height: 890 },
+    objects:  [{ name: "title", text: "Hello!" }]
+  }
+)
+
+# Open (unsigned): omit signing_key
+bb.build_instant_url(iurl["base_url"],
+  mode: "encoded",
+  modifications: { objects: [{ name: "title", text: "Hello!" }] }
+)
+```
+
+##### Options for `build_instant_url`
+
+- `mode`: `"encoded"` (default) or `"named_params"` (`string`)
+- `signing_key`: only needed when the instant URL was created with `security: "signed"` (`string`)
+- `modifications`: same shape as `create_image`'s modifications (`hash`)
+
+---
+
 ## Usage
 
 ### Table of Contents
@@ -33,6 +255,7 @@ Or install it yourself as:
 - [Templates](#templates)
 - [Template Sets](#template-sets)
 - [Video Templates](#video-templates)
+- [Signed URLs](#signed-urls)
 
 ### Authentication
 
@@ -333,6 +556,29 @@ bb.get_video_template("video template uid")
 bb.list_video_templates(:page => 2)
 ```
 
+### Signed URLs
+
+This gem also includes a convenient utility for generating signed urls. Authenticate as above, then:
+
+```ruby
+bb.generate_signed_url("base uid", :modifications => [])
+
+# example
+bb.generate_signed_url("A89wavQyY3Bebk3djP", 
+  :modifications => [
+    {
+      :name => "country", 
+      :text => "testing!"
+    },
+    {
+      :name => "photo", 
+      :image_url => "https://images.unsplash.com/photo-1638356435991-4c79b00ebef3?w=764&q=80"
+    }
+  ]
+)
+# https://ondemand.bannerbear.com/signedurl/A89wavQyY3Bebk3djP/image.jpg?modifications=W3sibmFtZSI6ImNvdW50cnkiLCJ0ZXh0IjoidGVzdGluZyEifSx7Im5hbWUiOiJwaG90byIsImltYWdlX3VybCI6Imh0dHBzOi8vaW1hZ2VzLnVuc3BsYXNoLmNvbS9waG90by0xNjM4MzU2NDM1OTkxLTRjNzliMDBlYmVmMz93PTc2NCZxPTgwIn1d&s=40e7c9d4902b86ea83e0c400e57d7cc580534fd527e234d40a0c7ace589a16eb
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/yongfook/bannerbear-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yongfook/bannerbear-ruby/blob/master/CODE_OF_CONDUCT.md).

data/lib/bannerbear/client.rb

@@ -109,8 +109,8 @@ module Bannerbear
 
     # Templates
 
-    def get_template(uid)
-    	get_response "/templates/#{uid}"
+    def get_template(uid, params = {})
+    	get_response "/templates/#{uid}?#{URI.encode_www_form(params.slice(:extended))}"
     end
 
     def update_template(uid, payload = {})
@@ -118,17 +118,17 @@ module Bannerbear
     end
 
     def list_templates(params = {})
-    	get_response "/templates?#{URI.encode_www_form(params.slice(:page, :tag, :limit, :name))}"
+    	get_response "/templates?#{URI.encode_www_form(params.slice(:page, :tag, :limit, :name, :extended))}"
     end
 
     # Template Sets
 
-    def get_template_set(uid)
-    	get_response "/template_sets/#{uid}"
+    def get_template_set(uid, params = {})
+    	get_response "/template_sets/#{uid}?#{URI.encode_www_form(params.slice(:extended))}"
     end
 
     def list_template_sets(params = {})
-    	get_response "/template_sets?#{URI.encode_www_form(params.slice(:page))}"
+    	get_response "/template_sets?#{URI.encode_www_form(params.slice(:page, :extended))}"
     end
 
     # Video Templates

data/lib/bannerbear/v5/client.rb

@@ -0,0 +1,199 @@
+module Bannerbear
+  module V5
+
+    class Client
+
+      def initialize(api_key = nil)
+        @api_key = api_key || ENV["BANNERBEAR_API_KEY"]
+      end
+
+      def account
+        get_response "/account"
+      end
+
+      # Image Templates
+
+      def list_image_templates(params = {})
+        get_response "/image_templates?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_image_template(uid)
+        get_response "/image_templates/#{uid}"
+      end
+
+      def update_image_template(uid, payload = {})
+        patch_response "/image_templates/#{uid}", payload.slice(:name, :description, :tags)
+      end
+
+      # Images
+
+      def list_images(params = {})
+        get_response "/images?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_image(uid)
+        get_response "/images/#{uid}"
+      end
+
+      def create_image(uid, payload = {})
+        post_response "/images", payload.slice(:modifications, :formats, :scale, :dpi, :quality, :proxy, :metadata, :version).merge({:template => uid}), payload[:sync]
+      end
+
+      # Batches
+
+      def list_batches(params = {})
+        get_response "/batches?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_batch(uid)
+        get_response "/batches/#{uid}"
+      end
+
+      def create_batch(payload = {})
+        post_response "/batches", payload.slice(:type, :items)
+      end
+
+      # Webhooks
+
+      def list_webhooks(params = {})
+        get_response "/webhooks?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_webhook(uid)
+        get_response "/webhooks/#{uid}"
+      end
+
+      def create_webhook(payload = {})
+        post_response "/webhooks", payload.slice(:name, :url, :resource, :event, :status, :scope, :templates)
+      end
+
+      def update_webhook(uid, payload = {})
+        patch_response "/webhooks/#{uid}", payload.slice(:name, :url, :resource, :event, :status, :scope, :templates)
+      end
+
+      def delete_webhook(uid)
+        delete_response "/webhooks/#{uid}"
+      end
+
+      # Instant URLs
+
+      def list_instant_urls(params = {})
+        get_response "/instant_urls?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_instant_url(uid)
+        get_response "/instant_urls/#{uid}"
+      end
+
+      def create_instant_url(payload = {})
+        post_response "/instant_urls", payload.slice(:name, :template, :mode, :security, :status, :scale, :rate_limit, :template_version, :max_renders, :expires_at)
+      end
+
+      def update_instant_url(uid, payload = {})
+        patch_response "/instant_urls/#{uid}", payload.slice(:name, :template, :mode, :security, :status, :scale, :rate_limit, :template_version, :max_renders, :expires_at)
+      end
+
+      def delete_instant_url(uid)
+        delete_response "/instant_urls/#{uid}"
+      end
+
+      def build_instant_url(base_url, payload = {})
+        modifications = payload[:modifications]
+        mode          = (payload[:mode] || "encoded").to_s
+
+        url = case mode
+              when "encoded"
+                data =
+                  if modifications.is_a?(Hash) && modifications.keys.map(&:to_s) == ["objects"]
+                    modifications[:objects] || modifications["objects"]
+                  else
+                    modifications
+                  end
+                "#{base_url}?modifications=#{Base64.urlsafe_encode64(data.to_json, padding: false)}"
+              when "named_params"
+                template = modifications.is_a?(Hash) ? (modifications[:template] || modifications["template"]) : nil
+                objects  = modifications.is_a?(Hash) ? (modifications[:objects]  || modifications["objects"])  : modifications
+                parts = []
+                (template || {}).each do |k, v|
+                  parts << "template:#{k}=#{URI.encode_www_form_component(v)}"
+                end
+                (objects || []).each do |obj|
+                  name = obj[:name] || obj["name"]
+                  obj.each do |k, v|
+                    key = k.to_s
+                    next if key == "name"
+                    parts << "#{name}:#{key}=#{URI.encode_www_form_component(v)}"
+                  end
+                end
+                "#{base_url}?#{parts.join('&')}"
+              else
+                raise ArgumentError, "unknown instant URL mode: #{mode.inspect}"
+              end
+
+        signing_key = payload[:signing_key]
+        return url if signing_key.nil? || signing_key.empty?
+        sig = OpenSSL::HMAC.hexdigest("SHA256", signing_key, url)
+        "#{url}&s=#{sig}"
+      end
+
+
+      private
+
+      BB_API_ENDPOINT = "https://api.bannerbear.com/v5"
+      BB_API_ENDPOINT_SYNCHRONOUS = "https://sync.api.bannerbear.com/v5"
+
+      def get_response(url)
+        response = HTTParty.get("#{BB_API_ENDPOINT}#{url}", timeout: 3, headers: { 'Authorization' => "Bearer #{@api_key}" })
+        body = JSON.parse(response.body)
+        return {"error" => body['message'], "code" => response.code} if response.code >= 400
+        return body
+      end
+
+      def patch_response(url, payload)
+        response = HTTParty.patch("#{BB_API_ENDPOINT}#{url}",
+          body: payload.to_json,
+          timeout: 5,
+          headers: {
+            'Authorization' => "Bearer #{@api_key}",
+            'Content-Type' => 'application/json'
+          }
+        )
+        body = JSON.parse(response.body)
+        return {"error" => body['message'], "code" => response.code} if response.code >= 400
+        return body
+      end
+
+      def post_response(url, payload, sync = false)
+        endpoint = BB_API_ENDPOINT
+        timeout = 5
+        if sync == true
+          endpoint = BB_API_ENDPOINT_SYNCHRONOUS
+          timeout = 10
+        end
+        response = HTTParty.post("#{endpoint}#{url}",
+          body: payload.to_json,
+          timeout: timeout,
+          headers: {
+            'Authorization' => "Bearer #{@api_key}",
+            'Content-Type' => 'application/json'
+          }
+        )
+        body = JSON.parse(response.body)
+        return {"error" => body['message'], "code" => response.code} if response.code >= 400
+        return body
+      end
+
+      def delete_response(url)
+        response = HTTParty.delete("#{BB_API_ENDPOINT}#{url}",
+          timeout: 5,
+          headers: { 'Authorization' => "Bearer #{@api_key}" }
+        )
+        body = response.body.to_s.empty? ? {} : JSON.parse(response.body)
+        return {"error" => body['message'], "code" => response.code} if response.code >= 400
+        return {"code" => response.code}
+      end
+
+    end
+
+  end
+end

data/lib/bannerbear/version.rb

@@ -1,3 +1,3 @@
 module Bannerbear
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/bannerbear.rb

@@ -1,8 +1,10 @@
 require "httparty"
 require "openssl"
 require "base64"
+require "json"
 require "bannerbear/version"
 require "bannerbear/client"
+require "bannerbear/v5/client"
 
 module Bannerbear
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bannerbear
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Jon Yongfook
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-02 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -43,6 +43,7 @@ files:
 - bin/setup
 - lib/bannerbear.rb
 - lib/bannerbear/client.rb
+- lib/bannerbear/v5/client.rb
 - lib/bannerbear/version.rb
 homepage: https://github.com/yongfook/bannerbear-ruby
 licenses:
@@ -64,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Ruby wrapper for the Bannerbear API