pictify 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61ccf483d399d895aed8467dd41ba36464a70b237c370cd03eb4a14911602a17
+  data.tar.gz: 168e24019d0d4e03c56866316a1557e397ed3c643d570ba6a9a0df49ddd2f601
+SHA512:
+  metadata.gz: 128158b9198f1a6388efad4a18152d0d563d9865b1ac306da1a280e8ad4e89882191cf912eb9a59d3ce4e1485e838861146de50a28ee55b2a52258dc1feb2c6e
+  data.tar.gz: f50e95a9dbb6e177021d512696be627a986f40e7b519712e2b994f2a920da6dae30832ccd6b8274dbb159e91308503c2de6d21ac4f94fd29a34535bfeb027d64

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-08
+
+### Changed (BREAKING)
+
+- Re-pointed the entire SDK to the real Pictify API. The previous `/v1/render*`
+  endpoints did not exist.
+- `render_html(html:, css:, width:, height:, selector:, format:)` now posts to
+  `POST /image` and returns an `ImageResult` (`url`, `id`, `created_at`). `css`
+  is injected as a `<style>` tag; `format` maps to `fileExtension`.
+- `render_url(url:, ...)` added — screenshots a live URL via `POST /image`.
+- `render(template_id:, variables:, format:, quality:, width:, height:, layout:, layouts:)`
+  posts to `POST /templates/:uid/render` and returns a `RenderResult` with a
+  `results` envelope; `result.url` returns the first result's URL.
+- `render_layouts(template_id:, layouts:, ...)` now takes explicit layout names
+  (max 20); failed layouts are returned in `errors`.
+- `render_gif(html:|url:|template_id:, variables:, width:, height:, quality:)`
+  posts to `POST /gif`, uses the `template` body key, accepts `quality`
+  (`:low`/`:medium`/`:high`), and flattens the `{ gif: {...} }` envelope into a
+  `GifRenderResult`.
+- `render_batch(template_id:, variable_sets:, format:, quality:, concurrency:, layout:, layouts:)`
+  is now asynchronous — posts to `POST /templates/:uid/batch-render` and returns
+  `BatchRenderResult` (`batch_id`, `status`, `total_items`).
+- `get_batch_results(batch_id)` added — polls `GET /templates/batch/:id/results`.
+  Per-item URLs are delivered via the `render.completed` webhook, not the poll.
+- `get_template(template_id)` unwraps the `{ template }` envelope; templates are
+  keyed by `uid` with `variable_definitions`.
+- `list_templates(page:, limit:, sort:)` returns `ListTemplatesResult`
+  (`templates`, `pagination`).
+- `create_template(html:, name:, width:, height:, variable_definitions:, output_format:)`
+  added — `POST /templates`.
+- Error mapping updated: 422 → `RenderError` (carries `errors`), 5xx →
+  `ServerError`, 429 with `quota_exceeded` → `QuotaExceededError`. Only 5xx and
+  network failures are retried; 4xx (including 429) are never retried.
+
+### Removed (BREAKING)
+
+- `render_stream` — no endpoint streams raw image bytes.
+- Legacy image fields (`image_url`, `render_id`, `device_scale_factor`,
+  `transparent`, `download`) and the frame-based GIF API.
+
+## [1.0.0] - 2026-01-23
+
+### Added
+
+- Initial release
+- `Pictify::Client` with render, render_html, render_gif, stream, batch, and template methods
+- Comprehensive error handling with specific error types
+- Automatic retry with exponential backoff
+- Support for all image formats (PNG, JPG, JPEG, WebP, GIF, PDF)
+- HTML render endpoint for rendering raw HTML directly
+- GIF render endpoint for creating animated GIFs
+- Rails and Sinatra integration examples

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pictify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,284 @@
+# Pictify Ruby SDK
+
+Official Ruby SDK for [Pictify](https://pictify.io) — generate images, PDFs, and GIFs from raw HTML, live URLs, and reusable templates.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "pictify"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install pictify
+```
+
+## Quick Start
+
+```ruby
+require "pictify"
+
+client = Pictify::Client.new(api_key: "your-api-key")
+
+# Render raw HTML to a PNG
+image = client.render_html(
+  html: "<div style='font-size:48px;padding:40px'>Hello World</div>",
+  width: 1200,
+  height: 630
+)
+puts image.url
+
+# Render a template
+result = client.render(
+  template_id: "your-template-uid",
+  variables: { name: "Ada", company: "Pictify" }
+)
+puts result.url
+```
+
+## Configuration
+
+```ruby
+client = Pictify::Client.new(
+  api_key: "your-api-key",
+  base_url: "https://api.pictify.io",  # Custom API URL
+  timeout: 30,                         # Request timeout in seconds
+  max_retries: 3                       # Max retry attempts (5xx / network only)
+)
+```
+
+## Rendering Images
+
+### From HTML — `POST /image`
+
+```ruby
+image = client.render_html(
+  html: "<div>Hello</div>",
+  css: "div { color: blue; }",  # injected as a <style> tag before rendering
+  width: 1200,                  # default 1280
+  height: 630,                  # default 720
+  selector: "#card",            # crop to a specific element (optional)
+  format: :png                  # :png, :jpg, :jpeg, :webp, :pdf — mapped to fileExtension
+)
+
+puts image.url         # CDN URL
+puts image.id          # image id
+puts image.created_at  # ISO timestamp
+```
+
+### From a live URL (screenshot) — `POST /image`
+
+```ruby
+image = client.render_url(
+  url: "https://example.com",
+  width: 1280,
+  height: 720,
+  selector: "#main",  # optional
+  format: :png        # optional
+)
+puts image.url
+```
+
+## Rendering Templates
+
+### Single render — `POST /templates/:uid/render`
+
+Returns a `results` array (one item per rendered layout). `result.url` is a
+convenience accessor for the first result's URL.
+
+```ruby
+result = client.render(
+  template_id: "your-template-uid",
+  variables: { title: "My Post", author: "Ada" },
+  format: :png,    # :png, :jpg, :jpeg, :webp, :pdf
+  quality: 0.9,    # raster quality 0.1–1.0
+  width: 1200,     # optional override
+  height: 630      # optional override
+)
+
+puts result.url               # results.first.url
+puts result.template_uid
+result.results.each do |item|
+  puts "#{item.layout}: #{item.url} (#{item.width}x#{item.height})"
+end
+```
+
+### Multiple layout variants — `POST /templates/:uid/render`
+
+Templates can have multiple layout variants (e.g. landscape, square, story)
+created via AI Resize in the Pictify editor. Render several in one call (max 20);
+layouts that fail land in `errors`.
+
+```ruby
+result = client.render_layouts(
+  template_id: "your-template-uid",
+  variables: { title: "Hello World" },
+  layouts: ["default", "twitter-post", "instagram-story"]
+)
+
+result.results.each do |item|
+  puts "#{item.layout}: #{item.url} (#{item.width}x#{item.height})"
+end
+result.errors.each do |err|
+  puts "#{err.layout} failed: #{err.error}"
+end
+
+puts "rendered #{result.total_rendered} of #{result.total_layouts}"
+```
+
+You can also render a single named variant via `render(..., layout: "square")`.
+
+## Rendering GIFs — `POST /gif`
+
+Provide exactly one source: `html`, `url`, or `template_id` (+ optional
+`variables`). The source must contain motion (CSS animation, etc.).
+
+```ruby
+gif = client.render_gif(
+  html: "<style>@keyframes p{0%{opacity:.2}50%{opacity:1}100%{opacity:.2}}" \
+        "div{animation:p 2s infinite}</style><div>Hi</div>",
+  width: 400,       # default 800
+  height: 200,      # default 600
+  quality: :medium  # :low, :medium, :high
+)
+puts gif.url
+puts gif.uid
+puts gif.animation_length
+
+# From a template
+gif = client.render_gif(template_id: "your-template-uid", variables: { name: "Ada" })
+
+# From a live URL
+gif = client.render_gif(url: "https://example.com/animated-page")
+```
+
+## Batch Rendering (async) — `POST /templates/:uid/batch-render`
+
+Batch rendering is asynchronous. Submitting returns a `batch_id` immediately;
+poll `get_batch_results` to track progress.
+
+> Note: the poll endpoint reports per-item `index`, `success`, and `variables`
+> but **not** rendered URLs — URLs are delivered via the `render.completed`
+> webhook.
+
+```ruby
+job = client.render_batch(
+  template_id: "your-template-uid",
+  variable_sets: [
+    { name: "Card 1", company: "X" },
+    { name: "Card 2", company: "Y" }
+  ],
+  format: :png,
+  quality: 0.9,    # optional
+  concurrency: 5,  # optional, 1–10
+  layouts: ["default", "twitter-post"]  # optional
+)
+
+puts job.batch_id
+puts job.status      # "pending"
+puts job.total_items
+
+# Poll for progress
+results = client.get_batch_results(job.batch_id)
+puts "status: #{results.status} (#{results.progress}%)"
+puts "completed: #{results.completed_items} / #{results.total_items}"
+results.results.each do |item|
+  puts "Item #{item.index}: success=#{item.success?} vars=#{item.variables}"
+end
+```
+
+## Template Management
+
+```ruby
+# Get a template by UID — GET /templates/:uid
+template = client.get_template("your-template-uid")
+puts "Template: #{template.name} (#{template.uid})"
+template.variable_definitions.each do |var|
+  puts "  - #{var.name} (#{var.type})"
+end
+
+# List templates — GET /templates
+result = client.list_templates(page: 1, limit: 20, sort: :newest)
+result.templates.each { |t| puts "#{t.uid}: #{t.name}" }
+puts "total: #{result.pagination.total}"
+
+# Create a template from HTML — POST /templates
+# Variables are auto-discovered from {{variableName}} tokens.
+template = client.create_template(
+  html: "<div>Hi {{firstName}}</div>",
+  name: "Welcome Card",
+  width: 600,
+  height: 200,
+  output_format: "image"  # "image" | "pdf"
+)
+puts template.uid
+```
+
+## Error Handling
+
+```ruby
+begin
+  result = client.render(template_id: "your-template-uid", variables: { name: "Ada" })
+rescue Pictify::AuthenticationError
+  puts "Invalid API key"
+rescue Pictify::TemplateNotFoundError => e
+  puts "Template not found: #{e.message}"
+rescue Pictify::QuotaExceededError
+  puts "Render quota exceeded"
+rescue Pictify::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after}s"
+rescue Pictify::RenderError => e
+  puts "Render/validation failed: #{e.message}"
+  puts e.errors  # field-level validation errors when present (422)
+rescue Pictify::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Pictify::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Pictify::TimeoutError
+  puts "Request timed out"
+rescue Pictify::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+| Status | Error class |
+|--------|-------------|
+| 401 | `Pictify::AuthenticationError` |
+| 402 | `Pictify::QuotaExceededError` |
+| 404 | `Pictify::TemplateNotFoundError` |
+| 422 | `Pictify::RenderError` (carries `errors`) |
+| 429 (`quota_exceeded`) | `Pictify::QuotaExceededError` |
+| 429 (other) | `Pictify::RateLimitError` |
+| other 4xx | `Pictify::RenderError` |
+| 5xx | `Pictify::ServerError` |
+
+Only 5xx responses and network failures are retried (with exponential backoff);
+4xx responses (including 429) are never retried.
+
+## Framework Example — Rails
+
+```ruby
+class OgImagesController < ApplicationController
+  def show
+    client = Pictify::Client.new(api_key: ENV["PICTIFY_API_KEY"])
+    image = client.render(
+      template_id: "og-image-template",
+      variables: { title: params[:title] }
+    )
+    redirect_to image.url, allow_other_host: true
+  end
+end
+```
+
+## License
+
+MIT

data/lib/pictify/client.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "cgi"
+
+module Pictify
+  # Client for the Pictify API.
+  #
+  # Generate images, PDFs, and GIFs from raw HTML, live URLs, and reusable
+  # templates.
+  #
+  # @example Render raw HTML to a PNG
+  #   client = Pictify::Client.new(api_key: "your-api-key")
+  #   image = client.render_html(html: "<div>Hello World</div>", width: 1200, height: 630)
+  #   puts image.url
+  #
+  # @example Render a template
+  #   result = client.render(template_id: "your-template-uid", variables: { name: "Ada" })
+  #   puts result.url # results.first.url
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://api.pictify.io"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+
+    # @param api_key [String] Your Pictify API key
+    # @param base_url [String] Custom API base URL
+    # @param timeout [Integer] Request timeout in seconds
+    # @param max_retries [Integer] Maximum retry attempts (5xx / network only)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+      raise AuthenticationError, "API key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+    end
+
+    # ------------------------------------------------------------------------
+    # Image rendering (POST /image)
+    # ------------------------------------------------------------------------
+
+    # Render an image (or PDF) directly from HTML.
+    #
+    # +POST /image+ — returns an {ImageResult} with +url+, +id+, +created_at+.
+    #
+    # @param html [String] Raw HTML content to render
+    # @param css [String, nil] Optional CSS, injected into the HTML inside a
+    #   <style> tag before rendering (the +/image+ endpoint takes a single +html+
+    #   field)
+    # @param width [Integer, nil] Output width in pixels (default 1280)
+    # @param height [Integer, nil] Output height in pixels (default 720)
+    # @param selector [String, nil] CSS selector to crop the screenshot to
+    # @param format [Symbol, String, nil] Output format, mapped to +fileExtension+
+    #   (default png)
+    # @return [ImageResult]
+    def render_html(html:, css: nil, width: nil, height: nil, selector: nil, format: nil)
+      body = css ? "<style>#{css}</style>#{html}" : html
+
+      response = request(:post, "image", {
+        html: body,
+        width: width,
+        height: height,
+        selector: selector,
+        fileExtension: (format || :png).to_s
+      })
+      ImageResult.new(response)
+    end
+
+    # Screenshot a live URL.
+    #
+    # +POST /image+ with +url+ — returns an {ImageResult}.
+    #
+    # @param url [String] The URL to screenshot
+    # @param width [Integer, nil] Output width in pixels (default 1280)
+    # @param height [Integer, nil] Output height in pixels (default 720)
+    # @param selector [String, nil] CSS selector to crop the screenshot to
+    # @param format [Symbol, String, nil] Output format, mapped to +fileExtension+
+    #   (default png)
+    # @return [ImageResult]
+    def render_url(url:, width: nil, height: nil, selector: nil, format: nil)
+      response = request(:post, "image", {
+        url: url,
+        width: width,
+        height: height,
+        selector: selector,
+        fileExtension: (format || :png).to_s
+      })
+      ImageResult.new(response)
+    end
+
+    # ------------------------------------------------------------------------
+    # Template rendering (POST /templates/:uid/render)
+    # ------------------------------------------------------------------------
+
+    # Render a single image (or PDF) from a template.
+    #
+    # +POST /templates/:uid/render+ — returns the {RenderResult} +results+
+    # envelope, with a convenience +url+ accessor (+results.first.url+).
+    #
+    # @param template_id [String] The UID of the template to render
+    # @param variables [Hash] Variables to inject into the template
+    # @param format [Symbol, String, nil] Output format (default png; +pdf+ supported)
+    # @param quality [Float, nil] Render quality for raster output (0.1–1.0, default 0.9)
+    # @param width [Integer, nil] Output width in pixels
+    # @param height [Integer, nil] Output height in pixels
+    # @param layout [String, nil] Render a single named layout variant
+    # @param layouts [Array<String>, nil] Render multiple named layout variants (max 20)
+    # @return [RenderResult]
+    def render(template_id:, variables: {}, format: nil, quality: nil, width: nil, height: nil,
+               layout: nil, layouts: nil)
+      response = request(:post, "templates/#{encode(template_id)}/render", {
+        variables: variables || {},
+        format: (format || :png).to_s,
+        quality: quality,
+        width: width,
+        height: height,
+        layout: layout,
+        layouts: layouts
+      })
+      RenderResult.new(response)
+    end
+
+    # Render multiple layout variants of a template in a single call.
+    #
+    # +POST /templates/:uid/render+ with +layouts+ — returns one +results+ item
+    # per successful layout; missing/invalid layouts appear in +errors+.
+    #
+    # @param template_id [String] The UID of the template to render
+    # @param layouts [Array<String>] Layout variant names to render (max 20).
+    #   Use +"default"+ for the base layout.
+    # @param variables [Hash] Variables to inject into the template
+    # @param format [Symbol, String, nil] Output format (default png)
+    # @param quality [Float, nil] Render quality for raster output (0.1–1.0)
+    # @param width [Integer, nil] Output width in pixels
+    # @param height [Integer, nil] Output height in pixels
+    # @return [RenderResult]
+    def render_layouts(template_id:, layouts:, variables: {}, format: nil, quality: nil,
+                       width: nil, height: nil)
+      render(
+        template_id: template_id,
+        variables: variables,
+        format: format,
+        quality: quality,
+        width: width,
+        height: height,
+        layouts: layouts
+      )
+    end
+
+    # ------------------------------------------------------------------------
+    # GIF rendering (POST /gif)
+    # ------------------------------------------------------------------------
+
+    # Render an animated GIF from raw HTML, a live URL, or a template.
+    #
+    # +POST /gif+ — the +{ gif: {...} }+ envelope is flattened to a
+    # {GifRenderResult} (+url+, +uid+, +width+, +height+, +animation_length+).
+    # Provide exactly one source: +html+, +url+, or +template_id+.
+    #
+    # @param html [String, nil] Raw HTML to render into a GIF (must contain motion)
+    # @param url [String, nil] A live URL to capture motion from
+    # @param template_id [String, nil] A template UID to render into a GIF
+    # @param variables [Hash, nil] Variables to inject when using +template_id+
+    # @param width [Integer, nil] Output width in pixels (default 800)
+    # @param height [Integer, nil] Output height in pixels (default 600)
+    # @param quality [Symbol, String, nil] Quality preset (:low, :medium, :high; default medium)
+    # @return [GifRenderResult]
+    def render_gif(html: nil, url: nil, template_id: nil, variables: nil, width: nil, height: nil,
+                   quality: nil)
+      response = request(:post, "gif", {
+        html: html,
+        url: url,
+        template: template_id,
+        variables: variables,
+        width: width,
+        height: height,
+        quality: (quality || :medium).to_s
+      })
+      GifRenderResult.new(response["gif"] || {})
+    end
+
+    # ------------------------------------------------------------------------
+    # Batch rendering (async)
+    # ------------------------------------------------------------------------
+
+    # Submit an async batch render of a template across many variable sets.
+    #
+    # +POST /templates/:uid/batch-render+ — returns a {BatchRenderResult} with
+    # +batch_id+, +status+, +total_items+ immediately (HTTP 202). Poll
+    # {#get_batch_results} to track progress.
+    #
+    # Rendered URLs are NOT returned by the poll endpoint — they are delivered
+    # via the +render.completed+ webhook.
+    #
+    # @param template_id [String] The UID of the template to render
+    # @param variable_sets [Array<Hash>] Variable sets — one render per set (max 100)
+    # @param format [Symbol, String, nil] Output format (default png)
+    # @param quality [Float, nil] Render quality for raster output (0.1–1.0, default 0.9)
+    # @param concurrency [Integer, nil] Maximum parallel renders (1–10, default 5)
+    # @param layout [String, nil] Render a single named layout variant for every item
+    # @param layouts [Array<String>, nil] Render multiple named layout variants for every item
+    # @return [BatchRenderResult]
+    def render_batch(template_id:, variable_sets:, format: nil, quality: nil, concurrency: nil,
+                     layout: nil, layouts: nil)
+      response = request(:post, "templates/#{encode(template_id)}/batch-render", {
+        variableSets: variable_sets,
+        format: (format || :png).to_s,
+        quality: quality,
+        concurrency: concurrency,
+        layout: layout,
+        layouts: layouts
+      })
+      BatchRenderResult.new(response)
+    end
+
+    # Get the status, progress, and per-item results of a batch job.
+    #
+    # +GET /templates/batch/:batch_id/results+. Results carry +index+, +success+,
+    # and +variables+ (plus +error+ on failures) but NOT rendered URLs.
+    #
+    # @param batch_id [String] The batch job ID returned by {#render_batch}
+    # @return [BatchResults]
+    def get_batch_results(batch_id)
+      response = request(:get, "templates/batch/#{encode(batch_id)}/results")
+      BatchResults.new(response)
+    end
+
+    # ------------------------------------------------------------------------
+    # Template CRUD
+    # ------------------------------------------------------------------------
+
+    # Get a single template by its UID.
+    #
+    # +GET /templates/:uid+ — unwraps the +{ template }+ envelope.
+    #
+    # @param template_id [String] The template UID
+    # @return [Template]
+    def get_template(template_id)
+      response = request(:get, "templates/#{encode(template_id)}")
+      Template.new(response["template"] || {})
+    end
+
+    # List templates in your account.
+    #
+    # +GET /templates+ — returns a {ListTemplatesResult} with +templates+ and
+    # +pagination+.
+    #
+    # @param page [Integer, nil] Page number (1-based, default 1)
+    # @param limit [Integer, nil] Items per page (max 100, default 12)
+    # @param sort [Symbol, String, nil] Sort order (:newest, :oldest, :name)
+    # @return [ListTemplatesResult]
+    def list_templates(page: nil, limit: nil, sort: nil)
+      params = {}
+      params[:page] = page unless page.nil?
+      params[:limit] = limit unless limit.nil?
+      params[:sort] = sort.to_s unless sort.nil?
+
+      response = request(:get, "templates", nil, params)
+      ListTemplatesResult.new(response)
+    end
+
+    # Create a template from HTML.
+    #
+    # +POST /templates+ — unwraps the +{ template }+ envelope. Variables are
+    # auto-discovered from +{{variableName}}+ tokens in the HTML body.
+    #
+    # @param html [String] Raw HTML body
+    # @param name [String, nil] Template name
+    # @param width [Integer, nil] Default width in pixels
+    # @param height [Integer, nil] Default height in pixels
+    # @param variable_definitions [Array<Hash>, nil] Explicit variable definitions
+    #   (auto-extracted from HTML when omitted)
+    # @param output_format [Symbol, String, nil] Output format ("image" | "pdf", default image)
+    # @return [Template]
+    def create_template(html:, name: nil, width: nil, height: nil, variable_definitions: nil,
+                        output_format: nil)
+      response = request(:post, "templates", {
+        html: html,
+        name: name,
+        width: width,
+        height: height,
+        variableDefinitions: variable_definitions,
+        outputFormat: output_format.nil? ? nil : output_format.to_s
+      })
+      Template.new(response["template"] || {})
+    end
+
+    private
+
+    def encode(value)
+      CGI.escape(value.to_s)
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |f|
+        f.request :retry,
+                  max: @max_retries,
+                  interval: 0.05,
+                  backoff_factor: 2,
+                  retry_statuses: [500, 502, 503, 504],
+                  # Keep faraday-retry's defaults (which include RetriableResponse
+                  # — required for retry_statuses to engage) and add network
+                  # failures so 5xx and connection drops retry, but 4xx never do.
+                  exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed],
+                  methods: %i[get post put delete patch]
+        f.options.timeout = @timeout
+        f.options.open_timeout = 10
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+        f.headers["Content-Type"] = "application/json"
+        f.headers["User-Agent"] = "pictify-ruby/#{VERSION}"
+      end
+    end
+
+    # Make an authenticated JSON request. Nil body fields are stripped so the
+    # backend applies its own defaults. HTTP errors are mapped to typed errors.
+    def request(method, path, body = nil, params = nil)
+      response = connection.send(method) do |req|
+        req.url(path, params)
+        req.body = JSON.generate(strip_nils(body)) if body
+      end
+
+      handle_response(response)
+    rescue Faraday::RetriableResponse => e
+      # faraday-retry re-raises this once retries on a retriable (5xx) status are
+      # exhausted; map the carried response through the typed-error logic.
+      env = e.response
+      raise Pictify.error_from_response(env.status, error_body(env.body))
+    rescue Faraday::TimeoutError
+      raise TimeoutError.new("Request timed out", timeout: @timeout)
+    rescue Faraday::ConnectionFailed => e
+      if e.message.include?("timeout") || e.message.include?("timed out") || e.message.include?("execution expired")
+        raise TimeoutError.new("Request timed out", timeout: @timeout)
+      end
+
+      raise NetworkError.new(nil, original_error: e)
+    end
+
+    def strip_nils(body)
+      return body unless body.is_a?(Hash)
+
+      body.reject { |_k, v| v.nil? }
+    end
+
+    def handle_response(response)
+      return parse_body(response.body) if response.success?
+
+      raise Pictify.error_from_response(response.status, error_body(response.body))
+    end
+
+    def parse_body(raw)
+      return {} if raw.nil? || raw.to_s.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def error_body(raw)
+      JSON.parse(raw)
+    rescue StandardError
+      { "message" => raw.to_s }
+    end
+  end
+end

data/lib/pictify/errors.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Pictify
+  # Base error class for all Pictify errors.
+  class Error < StandardError
+    attr_reader :status_code, :response_body
+
+    def initialize(message = nil, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      @raw_message = message || default_message
+      super(@raw_message)
+    end
+
+    def message
+      @raw_message
+    end
+
+    def to_s
+      return "[#{status_code}] #{@raw_message}" if status_code
+
+      @raw_message
+    end
+
+    private
+
+    def default_message
+      "An error occurred"
+    end
+  end
+
+  # Raised when the API key is invalid or missing (HTTP 401).
+  class AuthenticationError < Error
+    private
+
+    def default_message
+      "Invalid or missing API key"
+    end
+  end
+
+  # Raised when the specified template does not exist (HTTP 404).
+  class TemplateNotFoundError < Error
+    private
+
+    def default_message
+      "Template not found"
+    end
+  end
+
+  # Raised when the rate limit is exceeded (HTTP 429 without a quota code).
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      @retry_after = retry_after
+      super(message, **kwargs)
+    end
+
+    def to_s
+      base_str = super
+      return "#{base_str} (retry after #{retry_after}s)" if retry_after
+
+      base_str
+    end
+
+    private
+
+    def default_message
+      "Rate limit exceeded"
+    end
+  end
+
+  # Raised when the render quota is exceeded (HTTP 402, or 429 with a quota code).
+  class QuotaExceededError < Error
+    private
+
+    def default_message
+      "Render quota exceeded"
+    end
+  end
+
+  # Raised when a render fails or input validation fails (HTTP 422, and other
+  # non-quota 4xx). Carries field-level +errors+ from the API when present.
+  class RenderError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: nil, **kwargs)
+      @errors = errors
+      super(message, **kwargs)
+    end
+
+    private
+
+    def default_message
+      "Render failed"
+    end
+  end
+
+  # Raised when the server fails (HTTP 5xx).
+  class ServerError < Error
+    private
+
+    def default_message
+      "Server error"
+    end
+  end
+
+  # Raised when a network error occurs.
+  class NetworkError < Error
+    attr_reader :original_error
+
+    def initialize(message = nil, original_error: nil)
+      @original_error = original_error
+      super(message || original_error&.message || "Network error occurred")
+    end
+  end
+
+  # Raised when a request times out.
+  class TimeoutError < Error
+    attr_reader :timeout
+
+    def initialize(message = nil, timeout: nil)
+      @timeout = timeout
+      super(message || "Request timed out")
+    end
+  end
+
+  # Map an HTTP error response to a typed Pictify error.
+  #
+  # The Pictify API has no unified error envelope: image/GIF endpoints return
+  # +{ error, code }+ while template/CRUD endpoints return +{ message }+ or
+  # +{ message, errors }+. Message precedence is +error+ then +message+ then a
+  # fallback.
+  #
+  # Status mapping:
+  #   - 401            -> AuthenticationError
+  #   - 402            -> QuotaExceededError
+  #   - 404            -> TemplateNotFoundError
+  #   - 422            -> RenderError (validation; includes +errors+)
+  #   - 429            -> QuotaExceededError when code == "quota_exceeded", else RateLimitError
+  #   - other 4xx      -> RenderError
+  #   - 5xx            -> ServerError
+  def self.error_from_response(status_code, body)
+    body ||= {}
+    message = body["error"] || body["message"] || "An unexpected error occurred"
+
+    case status_code
+    when 401
+      AuthenticationError.new(message, status_code: status_code, response_body: body)
+    when 402
+      QuotaExceededError.new(message, status_code: status_code, response_body: body)
+    when 404
+      TemplateNotFoundError.new(message, status_code: status_code, response_body: body)
+    when 422
+      RenderError.new(message, status_code: status_code, response_body: body, errors: body["errors"])
+    when 429
+      if body["code"] == "quota_exceeded"
+        QuotaExceededError.new(message, status_code: status_code, response_body: body)
+      else
+        RateLimitError.new(message, status_code: status_code, response_body: body, retry_after: body["retry_after"])
+      end
+    else
+      if status_code >= 500
+        ServerError.new(message, status_code: status_code, response_body: body)
+      else
+        RenderError.new(message, status_code: status_code, response_body: body, errors: body["errors"])
+      end
+    end
+  end
+end

data/lib/pictify/types.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pictify
+  # Image output formats supported by Pictify renders.
+  #
+  # The +/image+ endpoint accepts these via +format+ (mapped to +fileExtension+);
+  # template renders accept them via +format+ (including +pdf+).
+  FORMATS = %i[png jpg jpeg webp pdf].freeze
+
+  # GIF quality presets accepted by the +/gif+ endpoint.
+  GIF_QUALITIES = %i[low medium high].freeze
+
+  # Result of an +/image+ render (+render_html+ / +render_url+).
+  #
+  # Maps the API response +{ url, id, createdAt }+.
+  class ImageResult
+    attr_reader :url, :id, :created_at, :raw
+
+    def initialize(data)
+      @raw = data
+      @url = data["url"]
+      @id = data["id"]
+      @created_at = data["createdAt"]
+    end
+  end
+
+  # A single rendered layout item within a template render response.
+  #
+  # Maps +{ layout, url, width, height, format, name, id, createdAt }+.
+  class RenderResultItem
+    attr_reader :layout, :url, :width, :height, :format, :name, :id, :created_at, :raw
+
+    def initialize(data)
+      @raw = data
+      @layout = data["layout"]
+      @url = data["url"]
+      @width = data["width"]
+      @height = data["height"]
+      @format = data["format"]
+      @name = data["name"]
+      @id = data["id"]
+      @created_at = data["createdAt"]
+    end
+  end
+
+  # Error entry returned when a specific layout fails to render.
+  #
+  # Maps +{ layout, error }+.
+  class RenderErrorEntry
+    attr_reader :layout, :error
+
+    def initialize(data)
+      @layout = data["layout"]
+      @error = data["error"]
+    end
+  end
+
+  # Result of a template render (+render+ / +render_layouts+).
+  #
+  # The API returns a +results[]+ envelope. The convenience method +url+ returns
+  # the URL of the first rendered item, or +nil+ if nothing rendered.
+  class RenderResult
+    attr_reader :results, :errors, :total_layouts, :total_rendered, :total_errors,
+                :template_uid, :raw
+
+    def initialize(data)
+      @raw = data
+      @results = (data["results"] || []).map { |r| RenderResultItem.new(r) }
+      @errors = (data["errors"] || []).map { |e| RenderErrorEntry.new(e) }
+      @total_layouts = data["totalLayouts"]
+      @total_rendered = data["totalRendered"]
+      @total_errors = data["totalErrors"]
+      @template_uid = data["templateUid"]
+    end
+
+    # Convenience accessor: URL of the first rendered item (+results[0].url+).
+    def url
+      results.first&.url
+    end
+  end
+
+  # Result of a GIF render (+render_gif+). Flattened from the API's
+  # +{ gif: {...} }+ envelope.
+  #
+  # Maps +{ url, uid, width, height, animationLength }+.
+  class GifRenderResult
+    attr_reader :url, :uid, :width, :height, :animation_length, :raw
+
+    def initialize(data)
+      @raw = data
+      @url = data["url"]
+      @uid = data["uid"]
+      @width = data["width"]
+      @height = data["height"]
+      @animation_length = data["animationLength"]
+    end
+  end
+
+  # Result of submitting an async batch render (+render_batch+).
+  #
+  # The job runs asynchronously: poll {Client#get_batch_results} with the
+  # returned +batch_id+ to track progress. Maps +{ batchId, status, totalItems }+.
+  class BatchRenderResult
+    attr_reader :batch_id, :status, :total_items, :message, :raw
+
+    def initialize(data)
+      @raw = data
+      @batch_id = data["batchId"]
+      @status = data["status"]
+      @total_items = data["totalItems"]
+      @message = data["message"]
+    end
+  end
+
+  # Status of a single item within a batch job.
+  #
+  # NOTE: batch results do NOT include rendered URLs — those are delivered via
+  # the +render.completed+ webhook. Each item reports only its index, success,
+  # the variable names it used, and (on failure) an error message.
+  class BatchItemStatus
+    attr_reader :index, :success, :variables, :error, :raw
+
+    def initialize(data)
+      @raw = data
+      @index = data["index"]
+      @success = data["success"]
+      @variables = data["variables"]
+      @error = data["error"]
+    end
+
+    def success?
+      !!@success
+    end
+  end
+
+  # Full status and progress of a batch job (+get_batch_results+).
+  #
+  # Maps +{ batchId, status, progress, totalItems, completedItems, failedItems,
+  # results[], errors[], createdAt, startedAt, completedAt }+.
+  class BatchResults
+    attr_reader :batch_id, :status, :progress, :total_items, :completed_items,
+                :failed_items, :results, :errors, :created_at, :started_at,
+                :completed_at, :raw
+
+    def initialize(data)
+      @raw = data
+      @batch_id = data["batchId"]
+      @status = data["status"]
+      @progress = data["progress"]
+      @total_items = data["totalItems"]
+      @completed_items = data["completedItems"]
+      @failed_items = data["failedItems"]
+      @results = (data["results"] || []).map { |r| BatchItemStatus.new(r) }
+      @errors = (data["errors"] || []).map { |e| BatchItemStatus.new(e) }
+      @created_at = data["createdAt"]
+      @started_at = data["startedAt"]
+      @completed_at = data["completedAt"]
+    end
+  end
+
+  # A variable definition declared on a template.
+  #
+  # The API keys variables by +name+ and may include +type+, +defaultValue+,
+  # +description+, and +validation+. Unknown engine-specific fields are kept in
+  # +raw+.
+  class TemplateVariableDefinition
+    attr_reader :name, :type, :default_value, :description, :validation, :raw
+
+    def initialize(data)
+      @raw = data
+      @name = data["name"]
+      @type = data["type"]
+      @default_value = data["defaultValue"]
+      @description = data["description"]
+      @validation = data["validation"]
+    end
+  end
+
+  # Template information returned by +get_template+ / +create_template+ /
+  # +list_templates+.
+  #
+  # The API keys templates by +uid+ (not +id+) and declares variables in
+  # +variableDefinitions+ (with a legacy flat +variables+ list of names).
+  # Unknown fields are passed through via +raw+.
+  class Template
+    attr_reader :uid, :name, :html, :width, :height, :engine, :output_format,
+                :variables, :variable_definitions, :thumbnail, :created_at,
+                :updated_at, :raw
+
+    def initialize(data)
+      @raw = data
+      @uid = data["uid"]
+      @name = data["name"]
+      @html = data["html"]
+      @width = data["width"]
+      @height = data["height"]
+      @engine = data["engine"]
+      @output_format = data["outputFormat"]
+      @variables = data["variables"] || []
+      @variable_definitions = (data["variableDefinitions"] || []).map do |v|
+        TemplateVariableDefinition.new(v)
+      end
+      @thumbnail = data["thumbnail"]
+      @created_at = parse_time(data["createdAt"])
+      @updated_at = parse_time(data["updatedAt"])
+    end
+
+    private
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # Pagination metadata returned by +list_templates+.
+  class Pagination
+    attr_reader :page, :limit, :total, :total_pages, :has_next, :has_prev, :raw
+
+    def initialize(data)
+      @raw = data
+      @page = data["page"]
+      @limit = data["limit"]
+      @total = data["total"]
+      @total_pages = data["totalPages"]
+      @has_next = data["hasNext"]
+      @has_prev = data["hasPrev"]
+    end
+
+    def has_next?
+      !!@has_next
+    end
+
+    def has_prev?
+      !!@has_prev
+    end
+  end
+
+  # Result of listing templates (+list_templates+).
+  #
+  # Maps +{ templates: [...], pagination: {...} }+.
+  class ListTemplatesResult
+    attr_reader :templates, :pagination, :raw
+
+    def initialize(data)
+      @raw = data
+      @templates = (data["templates"] || []).map { |t| Template.new(t) }
+      @pagination = data["pagination"] ? Pagination.new(data["pagination"]) : nil
+    end
+  end
+end

data/lib/pictify/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pictify
+  VERSION = "1.0.0"
+end

data/lib/pictify.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "pictify/version"
+require_relative "pictify/errors"
+require_relative "pictify/types"
+require_relative "pictify/client"
+
+# Pictify Ruby SDK
+#
+# Official SDK for generating images, PDFs, and GIFs from raw HTML, live URLs,
+# and reusable templates using the Pictify API.
+#
+# @example Render raw HTML to a PNG
+#   client = Pictify::Client.new(api_key: "your-api-key")
+#   image = client.render_html(html: "<div>Hello World</div>", width: 1200, height: 630)
+#   puts image.url
+#
+# @example Render a template
+#   result = client.render(
+#     template_id: "your-template-uid",
+#     variables: { name: "Ada", company: "Pictify" }
+#   )
+#   puts result.url
+#
+module Pictify
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: pictify
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Pictify
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Ruby client library for the Pictify API. Generate OG images, social cards,
+  and dynamic images from HTML templates.
+email:
+- support@pictify.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/pictify.rb
+- lib/pictify/client.rb
+- lib/pictify/errors.rb
+- lib/pictify/types.rb
+- lib/pictify/version.rb
+homepage: https://pictify.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://pictify.io
+  source_code_uri: https://github.com/pictify-io/pictify-ruby
+  changelog_uri: https://github.com/pictify-io/pictify-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.pictify.io/sdks/ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Pictify - Generate images from HTML templates
+test_files: []