screenshotcenter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ed56218652a0790a0d5881620b32144b126e7df27f10a3f4d77a41c6557c864
+  data.tar.gz: 3a297128e05c9c57377bfa5215689daa0ca96b416dc88426592a1ee244a2d4cd
+SHA512:
+  metadata.gz: 563aacf957e46b95c59bbbf6ec7d7003a15d7725c787a095ee7759585977f849525b906335115c42ab26821c6d2259c1472be7ed0bbfde94bbfffda191544b75
+  data.tar.gz: e8a040ff58b5bc2e7841494060a44bc5d941c9a3234c185b9637c9a0158720692d1a498a920ed2f8aedcd3a57b00c0325fe415a23988421b772d357e3b4551ee

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScreenshotCenter
+
+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,189 @@
+# screenshotcenter
+
+Official Ruby SDK for the [ScreenshotCenter](https://screenshotcenter.com) API.
+
+## Requirements
+
+- Ruby ≥ 2.5
+
+## Installation
+
+```bash
+gem install screenshotcenter
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "screenshotcenter"
+```
+
+## Quick start
+
+```ruby
+require "screenshotcenter"
+
+client = ScreenshotCenter::Client.new(ENV["SCREENSHOTCENTER_API_KEY"])
+
+shot   = client.screenshot.create("https://example.com")
+result = client.wait_for(shot["id"])
+puts result["url"]     # final URL
+puts result["status"]  # "finished"
+```
+
+## Use cases
+
+### Geo-targeting
+
+```ruby
+shot = client.screenshot.create("https://example.com",
+  country: "fr", lang: "fr-FR", tz: "Europe/Paris")
+```
+
+### PDF
+
+```ruby
+shot = client.screenshot.create("https://example.com", pdf: true)
+done = client.wait_for(shot["id"])
+client.screenshot.save_pdf(done["id"], "/tmp/page.pdf")
+```
+
+### HTML snapshot
+
+```ruby
+shot = client.screenshot.create("https://example.com", html: true)
+done = client.wait_for(shot["id"])
+client.screenshot.save_html(done["id"], "/tmp/page.html")
+```
+
+### Video
+
+```ruby
+shot = client.screenshot.create("https://example.com",
+  video: true, video_length: 5)
+done = client.wait_for(shot["id"])
+client.screenshot.save_video(done["id"], "/tmp/page.webm")
+```
+
+### Multiple shots
+
+```ruby
+shot = client.screenshot.create("https://example.com", shots: 5)
+done = client.wait_for(shot["id"])
+client.screenshot.save_image(done["id"], "/tmp/shot3.png", shot: 3)
+```
+
+### Save all artifacts
+
+```ruby
+done  = client.wait_for(shot["id"])
+files = client.screenshot.save_all(done["id"], "/tmp/screenshots")
+puts files[:image]  # /tmp/screenshots/1001.png
+```
+
+### Batch
+
+```ruby
+# Requires batch worker service to be running
+urls  = ["https://example.com", "https://example.org"]
+batch = client.batch.create(urls, "us")
+done  = client.batch.wait_for(batch["id"], interval: 3, timeout: 120)
+client.batch.save_zip(done["id"], "/tmp/batch.zip")
+```
+
+### Credit balance
+
+```ruby
+info = client.account.info
+puts info["balance"]
+```
+
+### Error handling
+
+```ruby
+begin
+  result = client.wait_for(shot["id"], interval: 2, timeout: 60)
+rescue ScreenshotCenter::ScreenshotFailedError => e
+  puts "Failed: #{e.reason}"
+rescue ScreenshotCenter::TimeoutError => e
+  puts "Timed out after #{e.timeout_ms}ms"
+rescue ScreenshotCenter::ApiError => e
+  puts "API error #{e.status}: #{e.message}"
+end
+```
+
+## API reference
+
+### `ScreenshotCenter::Client.new(api_key, base_url:, timeout:, http:)`
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | — | Required |
+| `base_url` | production | Override API base URL |
+| `timeout` | 30 | HTTP timeout in seconds |
+| `http` | built-in | Injectable HTTP transport for testing |
+
+### `client.screenshot`
+
+| Method | Description |
+|--------|-------------|
+| `create(url, **params)` | Create a screenshot |
+| `info(id)` | Get screenshot metadata |
+| `list(**params)` | List screenshots |
+| `search(url, **params)` | Search by URL |
+| `thumbnail(id, **params)` | Raw image bytes |
+| `html(id)` | Raw HTML bytes |
+| `pdf(id)` | Raw PDF bytes |
+| `video(id)` | Raw video bytes |
+| `delete(id, data:)` | Delete a screenshot |
+| `save_image(id, path, **params)` | Save image to disk |
+| `save_html(id, path)` | Save HTML to disk |
+| `save_pdf(id, path)` | Save PDF to disk |
+| `save_video(id, path)` | Save video to disk |
+| `save_all(id, directory, basename:)` | Save all artifacts |
+
+### `client.batch`
+
+| Method | Description |
+|--------|-------------|
+| `create(urls, country, **params)` | Create a batch |
+| `info(id)` | Get batch status |
+| `list(**params)` | List batches |
+| `download(id)` | Download ZIP bytes |
+| `save_zip(id, path)` | Save ZIP to disk |
+| `wait_for(id, interval:, timeout:)` | Poll until done |
+
+### `client.account`
+
+| Method | Description |
+|--------|-------------|
+| `info` | Get account info (balance, plan) |
+
+### `client.wait_for(id, interval: 2.0, timeout: 120.0)`
+
+Poll a screenshot until `finished` or `error`.
+
+## Testing
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `SCREENSHOTCENTER_API_KEY` | Required for integration tests |
+| `SCREENSHOTCENTER_BASE_URL` | Override base URL (default: production) |
+
+### Running tests
+
+```bash
+# Unit tests only — no credentials needed
+ruby spec/client_spec.rb
+
+# Integration tests against a local instance
+SCREENSHOTCENTER_API_KEY=your_key \
+SCREENSHOTCENTER_BASE_URL=http://localhost:3000/api/v1 \
+ruby spec/integration_spec.rb
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/screenshotcenter/client.rb

@@ -0,0 +1,317 @@
+require "net/http"
+require "uri"
+require "json"
+require "fileutils"
+require_relative "errors"
+
+module ScreenshotCenter
+  # ScreenshotCenter API client.
+  #
+  # @example
+  #   client = ScreenshotCenter::Client.new(ENV["SCREENSHOTCENTER_API_KEY"])
+  #   shot   = client.screenshot.create("https://example.com")
+  #   result = client.wait_for(shot["id"])
+  #   puts result["url"]
+  class Client
+    DEFAULT_BASE_URL = "https://api.screenshotcenter.com/api/v1"
+
+    attr_reader :screenshot, :batch, :account
+
+    # @param api_key  [String]   Your ScreenshotCenter API key (required).
+    # @param base_url [String]   Override the base URL (optional).
+    # @param timeout  [Integer]  HTTP read/open timeout in seconds (default 30).
+    # @param http     [#call]    Injectable HTTP transport for testing.
+    #                            Signature: http.call(method, uri, body, content_type) -> { status:, body:, content_type: }
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, http: nil)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key  = api_key
+      @base_url = base_url.chomp("/")
+      @timeout  = timeout
+      @http     = http || method(:default_http)
+
+      @screenshot = ScreenshotNamespace.new(self)
+      @batch      = BatchNamespace.new(self)
+      @account    = AccountNamespace.new(self)
+    end
+
+    # Poll a screenshot until it reaches +finished+ or +error+.
+    # @param interval [Float] seconds between polls (default 2)
+    # @param timeout  [Float] total seconds to wait (default 120)
+    def wait_for(id, interval: 2.0, timeout: 120.0)
+      deadline = Time.now + timeout
+      loop do
+        s = screenshot.info(id)
+        return s if s["status"] == "finished"
+        raise ScreenshotFailedError.new(id, s["error"]) if s["status"] == "error"
+        raise TimeoutError.new(id, (timeout * 1000).to_i) if Time.now + interval > deadline
+
+        sleep interval
+      end
+    end
+
+    # ── Internal helpers (used by namespaces) ─────────────────────────────────
+
+    # @!visibility private
+    def _get(endpoint, params = {})
+      resp = @http.call("GET", build_url(endpoint, params), nil, nil)
+      parse_response(resp)
+    end
+
+    # @!visibility private
+    def _get_bytes(endpoint, params = {})
+      resp = @http.call("GET", build_url(endpoint, params), nil, nil)
+      raise_if_error(resp)
+      resp[:body]
+    end
+
+    # @!visibility private
+    def _post(endpoint, body, content_type, params = {})
+      resp = @http.call("POST", build_url(endpoint, params), body, content_type)
+      parse_response(resp)
+    end
+
+    private
+
+    def build_url(endpoint, params)
+      merged = { key: @api_key }.merge(params)
+      parts = []
+      merged.each do |k, v|
+        next if v.nil?
+        if v.is_a?(Array)
+          if v.any? { |item| item.is_a?(Hash) }
+            parts << [k.to_s, JSON.generate(v)]
+          else
+            v.each { |item| parts << [k.to_s, item.to_s] }
+          end
+        elsif v.is_a?(Hash)
+          parts << [k.to_s, JSON.generate(v)]
+        else
+          parts << [k.to_s, v.to_s]
+        end
+      end
+      query = URI.encode_www_form(parts)
+      "#{@base_url}#{endpoint}?#{query}"
+    end
+
+    def parse_response(resp)
+      raise_if_error(resp)
+      data = JSON.parse(resp[:body])
+      if data.key?("success")
+        raise ApiError.new(data["error"] || "API error", status: resp[:status], code: data["code"], fields: data["fields"]) unless data["success"]
+        return data["data"]
+      end
+      data
+    rescue JSON::ParserError
+      raise Error, "Invalid JSON response"
+    end
+
+    def raise_if_error(resp)
+      return if resp[:status] >= 200 && resp[:status] < 300
+
+      data = JSON.parse(resp[:body]) rescue {}
+      raise ApiError.new(
+        data["error"] || "HTTP #{resp[:status]}",
+        status: resp[:status],
+        code:   data["code"],
+        fields: data["fields"]
+      )
+    end
+
+    def default_http(method, url, body, content_type)
+      uri  = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = case method
+                when "GET"  then Net::HTTP::Get.new(uri.request_uri)
+                when "POST" then Net::HTTP::Post.new(uri.request_uri)
+                end
+      if body
+        request.body = body
+        request["Content-Type"] = content_type if content_type
+      end
+
+      response = http.request(request)
+      { status: response.code.to_i, body: response.body.to_s, content_type: response["Content-Type"].to_s }
+    end
+  end
+
+  # ── Namespaces ───────────────────────────────────────────────────────────────
+
+  class ScreenshotNamespace
+    def initialize(client)
+      @client = client
+    end
+
+    def create(url, **params)
+      raise ArgumentError, '"url" is required' if url.nil? || url.empty?
+
+      @client._get("/screenshot/create", { url: url }.merge(params))
+    end
+
+    def info(id)
+      @client._get("/screenshot/info", { id: id })
+    end
+
+    def list(**params)
+      @client._get("/screenshot/list", params)
+    end
+
+    def search(url, **params)
+      raise ArgumentError, '"url" is required' if url.nil? || url.empty?
+
+      @client._get("/screenshot/search", { url: url }.merge(params))
+    end
+
+    def thumbnail(id, **params)
+      @client._get_bytes("/screenshot/thumbnail", { id: id }.merge(params))
+    end
+
+    def html(id)
+      @client._get_bytes("/screenshot/html", { id: id })
+    end
+
+    def pdf(id)
+      @client._get_bytes("/screenshot/pdf", { id: id })
+    end
+
+    def video(id)
+      @client._get_bytes("/screenshot/video", { id: id })
+    end
+
+    def delete(id, data: "all")
+      @client._get("/screenshot/delete", { id: id, data: data })
+    end
+
+    # ── File-save helpers ──────────────────────────────────────────────────────
+
+    def save_image(id, path, **params)
+      write_file(path, thumbnail(id, **params))
+    end
+
+    def save_pdf(id, path)
+      write_file(path, pdf(id))
+    end
+
+    def save_html(id, path)
+      write_file(path, html(id))
+    end
+
+    def save_video(id, path)
+      write_file(path, video(id))
+    end
+
+    def save_all(id, directory, basename: nil)
+      s    = info(id)
+      stem = basename || id.to_s
+      dir  = directory.chomp("/")
+      FileUtils.mkdir_p(dir)
+      saved = { image: nil, html: nil, pdf: nil, video: nil }
+
+      if s["status"] == "finished"
+        p = "#{dir}/#{stem}.png"
+        save_image(id, p)
+        saved[:image] = p
+      end
+      if s["has_html"]
+        p = "#{dir}/#{stem}.html"
+        save_html(id, p)
+        saved[:html] = p
+      end
+      if s["has_pdf"]
+        p = "#{dir}/#{stem}.pdf"
+        save_pdf(id, p)
+        saved[:pdf] = p
+      end
+      if s["has_video"]
+        ext = s["video_format"] || "webm"
+        p   = "#{dir}/#{stem}.#{ext}"
+        save_video(id, p)
+        saved[:video] = p
+      end
+      saved
+    end
+
+    private
+
+    def write_file(path, data)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.binwrite(path, data)
+    end
+  end
+
+  class BatchNamespace
+    def initialize(client)
+      @client = client
+    end
+
+    # @param urls    [String, Array<String>] newline-separated string or array
+    # @param country [String] required
+    def create(urls, country, **params)
+      raise ArgumentError, '"country" is required' if country.nil? || country.empty?
+
+      content = urls.is_a?(Array) ? urls.join("\n") : urls.to_s
+      body, content_type = build_multipart({ country: country }.merge(params), content)
+      @client._post("/batch/create", body, content_type)
+    end
+
+    def info(id)
+      @client._get("/batch/info", { id: id })
+    end
+
+    def list(**params)
+      @client._get("/batch/list", params)
+    end
+
+    def download(id)
+      @client._get_bytes("/batch/download", { id: id })
+    end
+
+    def save_zip(id, path)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.binwrite(path, download(id))
+    end
+
+    def wait_for(id, interval: 2.0, timeout: 120.0)
+      deadline = Time.now + timeout
+      loop do
+        b = info(id)
+        return b if %w[finished error].include?(b["status"])
+        raise TimeoutError.new(id, (timeout * 1000).to_i) if Time.now + interval > deadline
+
+        sleep interval
+      end
+    end
+
+    private
+
+    def build_multipart(fields, file_content)
+      boundary = "ScBoundary#{Time.now.to_i}"
+      body     = ""
+      fields.each do |name, value|
+        body += "--#{boundary}\r\n"
+        body += "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
+        body += "#{value}\r\n"
+      end
+      body += "--#{boundary}\r\n"
+      body += "Content-Disposition: form-data; name=\"file\"; filename=\"urls.txt\"\r\n"
+      body += "Content-Type: text/plain\r\n\r\n"
+      body += "#{file_content}\r\n"
+      body += "--#{boundary}--\r\n"
+      [body, "multipart/form-data; boundary=#{boundary}"]
+    end
+  end
+
+  class AccountNamespace
+    def initialize(client)
+      @client = client
+    end
+
+    def info
+      @client._get("/account/info")
+    end
+  end
+end

data/lib/screenshotcenter/errors.rb

@@ -0,0 +1,38 @@
+module ScreenshotCenter
+  # Base error class for all ScreenshotCenter exceptions.
+  class Error < StandardError; end
+
+  # Raised when the API returns a non-2xx status or success: false.
+  class ApiError < Error
+    attr_reader :status, :code, :fields
+
+    def initialize(message, status:, code: nil, fields: {})
+      super(message)
+      @status = status
+      @code   = code
+      @fields = fields || {}
+    end
+  end
+
+  # Raised by +wait_for+ when polling exceeds the timeout.
+  class TimeoutError < Error
+    attr_reader :screenshot_id, :timeout_ms
+
+    def initialize(screenshot_id, timeout_ms)
+      super("Screenshot #{screenshot_id} did not complete within #{timeout_ms}ms")
+      @screenshot_id = screenshot_id
+      @timeout_ms    = timeout_ms
+    end
+  end
+
+  # Raised by +wait_for+ when the screenshot status is "error".
+  class ScreenshotFailedError < Error
+    attr_reader :screenshot_id, :reason
+
+    def initialize(screenshot_id, reason = nil)
+      super("Screenshot #{screenshot_id} failed: #{reason || 'unknown error'}")
+      @screenshot_id = screenshot_id
+      @reason        = reason
+    end
+  end
+end

data/lib/screenshotcenter/version.rb

@@ -0,0 +1,3 @@
+module ScreenshotCenter
+  VERSION = "1.0.0"
+end

data/lib/screenshotcenter.rb

@@ -0,0 +1,3 @@
+require_relative "screenshotcenter/version"
+require_relative "screenshotcenter/errors"
+require_relative "screenshotcenter/client"

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: screenshotcenter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ScreenshotCenter
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.15.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.15.0
+description: Capture web screenshots, PDFs, HTML snapshots, and videos at scale.
+email:
+- support@screenshotcenter.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/screenshotcenter.rb
+- lib/screenshotcenter/client.rb
+- lib/screenshotcenter/errors.rb
+- lib/screenshotcenter/version.rb
+homepage: https://screenshotcenter.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6.3
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for the ScreenshotCenter API
+test_files: []