bannerbear 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a63e7f3269afc788dea97a56ba271553cce7ae8ad8c605246321be788bbe5601
-  data.tar.gz: 68aa7455b8b4b71ddcf47ee0a59563d0a36f437670822680b9030ff0d41993a2
+  metadata.gz: 850108dc51b0e1e90d1e7e6452ce69b65c972638e33d7f6b946f0f81ab4fe1cd
+  data.tar.gz: f4c1e8883281527d9c515a07d358a251629ec19fb06a2dab4506fb95cfd9576a
 SHA512:
-  metadata.gz: 2e4cc99311a703073a184a5211bf1c7c14b18df1062b03592558368e4d017d3f5e116f1c7948c63703300bb4af6cc6da5c0b15bdaf5942e4a1465624fc89c0af
-  data.tar.gz: a3017ce751ebfac3260bd7f174b61040ac2c0130a28f13ced336f7d77e0944507a195ef28aba8701d706fc4b6bef8d5b428a7ee3e51bfa716ef92fddf33af26a
+  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.4)
+    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.2022.0105)
-    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

@@ -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

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.4"
+  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.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Jon Yongfook
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-07-20 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