shotwolf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00d361d43de9b07008915a8608e0627fde4404af97c404107923954d6fc6ffb1
+  data.tar.gz: 9aaae813882af6789f98ec7e02383ac0206da3f6960cf83f5b212a88e3f15aef
+SHA512:
+  metadata.gz: 6e8b2d63c50dbb61b8ca0bc4e862b460d58e5e3564740744d596f615604a98ce169c549ab472340f317ea2b220496ee7374735a75b69eceaf3787e70657c7565
+  data.tar.gz: d51af6312dbb4c138fca01cf10fe70da8a33ec88ceadf09d815e34834348914f105e6a750d74a9db83934d62cc2fa3cfe0b3db212e815fd5464aa78c9862879a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShotWolf
+
+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,144 @@
+# ShotWolf Ruby SDK
+
+Official Ruby client for the [ShotWolf](https://shotwolf.com) API - capture screenshots, render device mockups, generate Open Graph cards, convert HTML to PDF, and run pixel-level visual regression diffs through a single JSON HTTP API.
+
+- Zero dependencies (standard library only, Ruby 3.0+)
+- Built-in retries with backoff, idempotency keys, and an async polling helper
+
+## Install
+
+```bash
+gem install shotwolf
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "shotwolf"
+```
+
+## Quick start
+
+Get an API key at [shotwolf.com/dashboard/api_keys](https://shotwolf.com/dashboard/api_keys).
+
+```ruby
+require "shotwolf"
+
+sw = Shotwolf::Client.new  # reads SHOTWOLF_API_KEY, or pass Shotwolf::Client.new("sw_live_...")
+
+shot = sw.capture(url: "https://example.com", full_page: true, dismiss_cookies: true)
+puts shot["image_url"]
+```
+
+## Usage
+
+### Screenshots
+
+```ruby
+# Sync - returns the image URL inline (~1-4s)
+shot = sw.capture(url: "https://stripe.com", device: "iphone_15_pro")
+
+# Async - queue and poll (or pass webhook_url for a callback)
+queued = sw.capture_async(url: "https://stripe.com")
+done = sw.wait_for(queued["id"])  # polls until status is done
+
+# Batch - one page, many viewports (cheaper than N calls)
+batch = sw.batch(url: "https://stripe.com", devices: ["default", "iphone_15_pro", "ipad_pro_12_9"])
+```
+
+### Device & social mockups
+
+```ruby
+mockup = sw.mockup(url: "https://stripe.com", frame: "macbook_air", bg: "gradient")
+```
+
+### Open Graph cards
+
+```ruby
+og = sw.og(template: "blog_card", variables: { title: "Ship faster", author: "Jane Doe" })
+```
+
+### HTML / URL to PDF
+
+```ruby
+pdf = sw.pdf(html: "<h1>Invoice #42</h1>", page_format: "A4", print_background: true)
+```
+
+### Visual regression diff
+
+```ruby
+diff = sw.diff(
+  before_url: "https://staging.example.com",
+  after_url: "https://example.com",
+  ignore_regions: [{ x: 0, y: 0, width: 1280, height: 80 }]  # mask a dynamic header
+)
+puts "#{(diff['diff_ratio'] * 100).round(2)}% changed" unless diff["passed"]
+```
+
+### Account balance
+
+```ruby
+account = sw.account
+puts account["balance_cr"], account["tier"]["name"]
+```
+
+## Idempotency
+
+Pass `idempotency_key:` to make money-charging POSTs safe to retry. A repeat with
+the same key and body within 24h replays the original response instead of
+charging again.
+
+```ruby
+require "securerandom"
+sw.capture(url: "https://example.com", idempotency_key: SecureRandom.uuid)
+```
+
+## Error handling
+
+Any non-2xx response raises `Shotwolf::Error` carrying the API error `type`, HTTP
+`status`, and `message`.
+
+```ruby
+begin
+  sw.capture(url: "https://example.com")
+rescue Shotwolf::Error => e
+  # e.type == "insufficient_credits" -> top up at https://shotwolf.com/pricing
+  warn [e.status, e.type, e.message, e.request_id].inspect
+end
+```
+
+## Configuration
+
+```ruby
+sw = Shotwolf::Client.new(
+  "sw_live_xxx",
+  base_url: "https://shotwolf.com",  # override for self-host / testing
+  timeout: 60,                       # per-request timeout in seconds
+  max_retries: 2,                    # retries on 429 / 5xx
+  retry_backoff: 0.5                 # base backoff, doubled per attempt
+)
+```
+
+Retries honor the `Retry-After` header on `429` responses. `4xx` responses
+other than `429` are never retried.
+
+## API coverage
+
+| Method | Endpoint |
+| --- | --- |
+| `capture(**params)` | `POST /api/v1/captures` |
+| `capture_async(**params)` | `POST /api/v1/captures/async` |
+| `batch(**params)` | `POST /api/v1/capture/batch` |
+| `mockup(**params)` | `POST /api/v1/mockups` |
+| `og(**params)` | `POST /api/v1/og` |
+| `pdf(**params)` | `POST /api/v1/pdf` |
+| `diff(**params)` | `POST /api/v1/diffs` |
+| `get_screenshot(id)` | `GET /api/v1/screenshots/:id` |
+| `wait_for(id)` | polls `get_screenshot` until `done`/`failed` |
+| `account` | `GET /api/v1/account` |
+
+Full parameter reference: [shotwolf.com/docs](https://shotwolf.com/docs).
+
+## License
+
+MIT

data/lib/shotwolf/client.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require_relative "version"
+require_relative "errors"
+
+module Shotwolf
+  # Client for the ShotWolf API. Pass an API key (+sw_live_...+) or set the
+  # +SHOTWOLF_API_KEY+ environment variable.
+  #
+  #   sw = Shotwolf::Client.new
+  #   shot = sw.capture(url: "https://example.com", device: "iphone_15_pro")
+  #   puts shot["image_url"]
+  class Client
+    DEFAULT_BASE_URL = "https://shotwolf.com"
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    def initialize(api_key = nil, base_url: DEFAULT_BASE_URL, timeout: 60, max_retries: 2,
+                   retry_backoff: 0.5, transport: nil)
+      @api_key = api_key || ENV.fetch("SHOTWOLF_API_KEY", nil)
+      if @api_key.nil? || @api_key.empty?
+        raise Error.new("Missing API key. Pass api_key or set SHOTWOLF_API_KEY.", type: "unauthorized")
+      end
+
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+      @retry_backoff = retry_backoff
+      @transport = transport || method(:net_http_transport)
+    end
+
+    # Capture a URL or HTML synchronously. POST /api/v1/captures
+    def capture(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/captures", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Queue a capture and return immediately. POST /api/v1/captures/async
+    def capture_async(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/captures/async", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Render one URL across 2-6 devices. POST /api/v1/capture/batch
+    def batch(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/capture/batch", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Render a URL inside a device/social mockup. POST /api/v1/mockups
+    def mockup(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/mockups", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Generate an Open Graph card from a template. POST /api/v1/og
+    def og(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/og", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Convert a URL or HTML string to PDF. POST /api/v1/pdf
+    def pdf(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/pdf", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Pixel-diff two screenshots. POST /api/v1/diffs
+    def diff(idempotency_key: nil, timeout: nil, **params)
+      request("POST", "/api/v1/diffs", body: params, idempotency_key: idempotency_key, timeout: timeout)
+    end
+
+    # Retrieve a single screenshot by ID. GET /api/v1/screenshots/:id
+    def get_screenshot(id, timeout: nil)
+      request("GET", "/api/v1/screenshots/#{id.to_i}", timeout: timeout)
+    end
+
+    # Get balance, tier and webhook secret. GET /api/v1/account
+    def account(timeout: nil)
+      request("GET", "/api/v1/account", timeout: timeout)
+    end
+
+    # Poll +get_screenshot+ until the shot is +done+ or +failed+. Returns the
+    # final screenshot Hash; raises Shotwolf::Error on render failure or
+    # Shotwolf::TimeoutError if the deadline passes.
+    def wait_for(id, interval: 2.0, timeout: 120.0)
+      deadline = monotonic + timeout
+      loop do
+        shot = get_screenshot(id)
+        return shot if shot["status"] == "done"
+        if shot["status"] == "failed"
+          raise Error.new("Screenshot #{id} failed to render", type: "render_failed", status: 422)
+        end
+        raise TimeoutError.new(timeout) if monotonic + interval > deadline
+
+        sleep(interval)
+      end
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def request(method, path, body: nil, idempotency_key: nil, timeout: nil)
+      url = @base_url + path
+      req_timeout = timeout || @timeout
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "shotwolf-ruby/#{VERSION}"
+      }
+      payload = nil
+      unless body.nil?
+        headers["Content-Type"] = "application/json"
+        payload = JSON.generate(body)
+      end
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+      last_error = nil
+      (0..@max_retries).each do |attempt|
+        begin
+          status, resp_headers, resp_body = @transport.call(method, url, headers, payload, req_timeout)
+        rescue StandardError => e
+          last_error = timeout_error?(e) ? TimeoutError.new(req_timeout) : e
+          if attempt < @max_retries
+            sleep(backoff(attempt))
+            next
+          end
+          raise last_error
+        end
+
+        if status >= 200 && status < 300
+          return resp_body.nil? || resp_body.empty? ? {} : JSON.parse(resp_body)
+        end
+
+        if RETRYABLE_STATUSES.include?(status) && attempt < @max_retries
+          sleep(parse_retry_after(resp_headers) || backoff(attempt))
+          next
+        end
+
+        raise to_error(status, resp_headers, resp_body)
+      end
+
+      raise(last_error || Error.new("Request failed"))
+    end
+
+    def net_http_transport(method, url, headers, body, timeout)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+
+      klass = method == "GET" ? Net::HTTP::Get : Net::HTTP::Post
+      req = klass.new(uri.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body
+
+      resp = http.request(req)
+      resp_headers = {}
+      resp.each_header { |k, v| resp_headers[k.downcase] = v }
+      [resp.code.to_i, resp_headers, resp.body]
+    end
+
+    def timeout_error?(err)
+      err.is_a?(Timeout::Error) || err.is_a?(Net::OpenTimeout) || err.is_a?(Net::ReadTimeout)
+    end
+
+    def backoff(attempt)
+      @retry_backoff * (2**attempt)
+    end
+
+    def parse_retry_after(headers)
+      raw = headers["retry-after"]
+      return nil unless raw
+
+      Float(raw)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def to_error(status, headers, body)
+      type = nil
+      message = "HTTP #{status}"
+      begin
+        data = JSON.parse(body.to_s)
+        if data.is_a?(Hash) && data["error"].is_a?(Hash)
+          type = data["error"]["type"]
+          message = data["error"]["message"] || message
+        end
+      rescue JSON::ParserError
+        # non-JSON body; keep the HTTP status message
+      end
+      Error.new(
+        message,
+        type: type || "unknown",
+        status: status,
+        request_id: headers["x-request-id"],
+        retry_after: parse_retry_after(headers)
+      )
+    end
+  end
+end

data/lib/shotwolf/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Shotwolf
+  # Raised for any non-2xx API response. +type+ mirrors the API error envelope
+  # (invalid_params, insufficient_credits, rate_limited, ...). +status+ is the
+  # HTTP status code (0 for client-side/transport errors).
+  class Error < StandardError
+    attr_reader :type, :status, :request_id, :retry_after
+
+    def initialize(message, type: "unknown", status: 0, request_id: nil, retry_after: nil)
+      super(message)
+      @type = type
+      @status = status
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised when a request exceeds the configured timeout.
+  class TimeoutError < Error
+    def initialize(timeout)
+      super("Request timed out after #{timeout}s", type: "timeout", status: 0)
+    end
+  end
+end

data/lib/shotwolf/version.rb

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

data/lib/shotwolf.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "shotwolf/version"
+require_relative "shotwolf/errors"
+require_relative "shotwolf/client"
+
+# Official Ruby SDK for the ShotWolf API - https://shotwolf.com
+module Shotwolf
+  # Convenience: Shotwolf.new(...) == Shotwolf::Client.new(...)
+  def self.new(...)
+    Client.new(...)
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: shotwolf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ShotWolf
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-21 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client for the ShotWolf API - capture screenshots, render device
+  mockups, generate Open Graph cards, convert HTML to PDF, and run pixel-level visual
+  regression diffs through a single JSON HTTP API. Zero dependencies.
+email:
+- hello@shotwolf.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/shotwolf.rb
+- lib/shotwolf/client.rb
+- lib/shotwolf/errors.rb
+- lib/shotwolf/version.rb
+homepage: https://shotwolf.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://shotwolf.com
+  source_code_uri: https://github.com/shotwolf/ruby
+  documentation_uri: https://shotwolf.com/docs/sdks/
+  bug_tracker_uri: https://github.com/shotwolf/ruby/issues
+  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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the ShotWolf screenshot, mockup, OG image, HTML-to-PDF
+  and visual-diff API.
+test_files: []