screenshotfreeapi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a74c7308a606f4b35000f23f5acd86ddbe75e8b924babc380474d75d758a1d32
+  data.tar.gz: fa76ec1108119c0279dde70d5498b5f818dc5aa14fb446e173ae64b2e6bf8943
+SHA512:
+  metadata.gz: 686cb5b19cb4b36f59d180164c355a2474d690d3e1735e48a9be0fa708e00ea6c1a7afe37e387f7c5a4faaa0daeb995194865932f043a124c4fc7896a8329274
+  data.tar.gz: 5e6951a5d5310c3eb0fa78b05b156140461ca7627da59e03fae588d3354a65283569df390f15564dc35dcd64b1e17c6154131cc2ae9448226d5247cfd33d75f6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScreenshotFreeAPI
+
+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,442 @@
+# ScreenshotFreeAPI — Ruby SDK
+
+Official Ruby client for [ScreenshotFreeAPI](https://api.screenshotfreeapi.com) — screenshot-as-a-service.
+
+- Capture web pages, mobile app store listings, and HTML strings
+- Async job polling with configurable timeout
+- Webhook signature verification (HMAC-SHA256)
+- Billing, workspace, and monitor management
+- Zero runtime dependencies — stdlib only (`net/http`, `json`, `openssl`)
+- Ruby 2.7+ compatible
+
+---
+
+## Installation
+
+### RubyGems
+
+```bash
+gem install screenshotfreeapi
+```
+
+### Bundler
+
+Add to your `Gemfile`:
+
+```ruby
+gem "screenshotfreeapi", "~> 1.0"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+---
+
+## Quick Start
+
+```ruby
+require "screenshotfreeapi"
+
+client = ScreenshotFreeAPI.new(api_key: ENV["SCREENSHOTFREEAPI_KEY"])
+
+# Capture a URL and wait for the result (blocks until complete)
+result = client.capture("https://stripe.com/pricing")
+
+puts result["screenshots"].first["url"]
+# => "https://s3.amazonaws.com/...?X-Amz-Expires=900"
+```
+
+---
+
+## All Screenshot Types
+
+### Web Screenshot
+
+```ruby
+client = ScreenshotFreeAPI.new(api_key: ENV["SCREENSHOTFREEAPI_KEY"])
+
+# Enqueue (returns immediately with a job receipt)
+job = client.screenshots.web(
+  url:            "https://stripe.com/pricing",
+  format:         "png",          # "png" | "jpeg" | "webp" | "pdf"
+  full_page:      true,           # capture the full scrollable page
+  dimensions:     { width: 1440, height: 900 },
+  block_ads:      true,           # STARTER+
+  accept_cookies: true,           # STARTER+
+  webhook_url:    "https://yourapp.com/webhooks/screenshot-events"
+)
+
+puts job["jobId"]      # => "clxyz123"
+puts job["statusUrl"]  # => "/jobs/clxyz123/status"
+
+# --- AI-targeted element capture ---
+job = client.screenshots.web(
+  url:         "https://stripe.com/pricing",
+  description: "the pricing comparison table"  # triggers Claude vision path
+)
+
+# --- CSS selector targeting ---
+job = client.screenshots.web(
+  url:     "https://github.com",
+  element: ".hero-section"
+)
+
+# --- Enqueue and block until done ---
+result = client.screenshots.web_and_wait(
+  url:    "https://example.com",
+  format: "png"
+)
+puts result["screenshots"].first["url"]
+```
+
+### Mobile App Screenshot
+
+```ruby
+# Store listing screenshots
+job = client.screenshots.mobile(
+  app_name:              "Instagram",
+  platform:              "both",           # "ios" | "android" | "both"
+  bundle_id:             "com.instagram.android",
+  include_store_listing: true,
+  device_emulation:      "iPhone 12"
+)
+
+# Block until complete
+result = client.screenshots.mobile_and_wait(
+  app_name: "Spotify",
+  platform: "ios"
+)
+puts result["screenshots"].map { |s| s["url"] }
+```
+
+### HTML String Screenshot
+
+```ruby
+html_content = <<~HTML
+  <!DOCTYPE html>
+  <html>
+    <body style="font-family: sans-serif; padding: 40px;">
+      <h1>Invoice #1042</h1>
+      <p>Total: <strong>$149.00</strong></p>
+    </body>
+  </html>
+HTML
+
+result = client.screenshots.html_and_wait(
+  html:      html_content,
+  format:    "png",
+  full_page: true,
+  dimensions: { width: 800, height: 600 }
+)
+puts result["screenshots"].first["url"]
+```
+
+---
+
+## Manual Polling
+
+If you want to enqueue a job and check on it yourself:
+
+```ruby
+# 1. Enqueue
+job = client.screenshots.web(url: "https://example.com")
+job_id = job["jobId"]
+
+# 2. Poll manually
+loop do
+  status = client.jobs.status(job_id)
+  puts "#{status["status"]} — #{status["progress"]}%"
+  break if status["status"] == "completed"
+  raise "Job failed: #{status["error"]}" if status["status"] == "failed"
+  sleep 2
+end
+
+# 3. Fetch result
+result = client.jobs.result(job_id)
+puts result["screenshots"].first["url"]
+```
+
+Or use the built-in `wait` method with a progress callback:
+
+```ruby
+result = client.screenshots.wait(job_id, poll_interval: 3, timeout: 180) do |status|
+  puts "[#{status["status"]}] #{status["progress"]}%"
+end
+```
+
+---
+
+## Authentication
+
+```ruby
+# Register a new account (returns apiKey shown once only)
+account = client.auth.register(
+  email:    "you@example.com",
+  password: "securepassword123!",
+  name:     "Your Name"
+)
+puts account["apiKey"]  # store this securely
+
+# Get a management JWT (needed for billing / workspaces / monitors)
+token_data = client.auth.token(
+  email:    "you@example.com",
+  password: "securepassword123!"
+)
+jwt = token_data["token"]
+
+# Refresh an expiring JWT
+new_token = client.auth.refresh(refresh_token: "your_refresh_token")
+```
+
+---
+
+## Error Handling
+
+```ruby
+require "screenshotfreeapi"
+
+client = ScreenshotFreeAPI.new(api_key: ENV["SCREENSHOTFREEAPI_KEY"])
+
+begin
+  result = client.capture("https://example.com")
+
+rescue ScreenshotFreeAPI::AuthenticationError => e
+  # 401 — API key is missing or invalid
+  puts "Authentication failed: #{e.message}"
+
+rescue ScreenshotFreeAPI::PaymentRequiredError => e
+  # 402 — Subscription cancelled or payment overdue
+  puts "Payment required: #{e.message}"
+
+rescue ScreenshotFreeAPI::ForbiddenError => e
+  # 403 — API key revoked or account suspended
+  puts "Forbidden: #{e.message}"
+
+rescue ScreenshotFreeAPI::NotFoundError => e
+  # 404 — Job not found or not owned by this API key
+  puts "Not found: #{e.message}"
+
+rescue ScreenshotFreeAPI::ValidationError => e
+  # 400 — Request body failed server-side validation
+  puts "Validation error: #{e.message}"
+  puts "Details: #{e.details.inspect}" if e.details
+
+rescue ScreenshotFreeAPI::RateLimitError => e
+  # 429 per-minute rate limit
+  puts "Rate limited. Retry after #{e.retry_after}s"
+  sleep(e.retry_after || 60)
+  retry
+
+rescue ScreenshotFreeAPI::QuotaExceededError => e
+  # 429 monthly quota exhausted
+  puts "Monthly quota exceeded: #{e.message}"
+
+rescue ScreenshotFreeAPI::JobFailedError => e
+  # Job transitioned to "failed" during polling
+  puts "Job #{e.job_id} failed: #{e.reason}"
+
+rescue ScreenshotFreeAPI::JobTimeoutError => e
+  # Job did not complete within the polling timeout
+  puts "Job #{e.job_id} timed out after #{e.timeout_seconds}s"
+
+rescue ScreenshotFreeAPI::ScreenshotFreeAPIError => e
+  # Catch-all for unexpected HTTP errors (5xx, etc.)
+  puts "API error #{e.status_code}: #{e.message}"
+end
+```
+
+---
+
+## Billing
+
+```ruby
+# Get JWT first
+jwt = client.auth.token(email: "you@example.com", password: "secret")["token"]
+
+# List available plans (no auth needed)
+plans = client.billing.plans
+plans.each { |p| puts "#{p["name"]}: $#{p["price"]}/mo" }
+
+# Current plan and usage
+plan  = client.billing.plan(jwt: jwt)
+usage = client.billing.usage(jwt: jwt)
+puts "Plan: #{plan["plan"]}, Used: #{plan["screenshotsUsed"]}"
+
+# Upgrade
+checkout = client.billing.upgrade(jwt: jwt, plan: "GROWTH")
+puts "Complete payment at: #{checkout["checkoutUrl"]}"
+
+# Verify payment after redirect
+verified = client.billing.verify(jwt: jwt, transaction_ref: checkout["transactionRef"])
+puts verified["message"]
+
+# Cancel
+client.billing.cancel(jwt: jwt)
+```
+
+---
+
+## Workspaces
+
+```ruby
+jwt = client.auth.token(email: "you@example.com", password: "secret")["token"]
+
+# Create
+workspace = client.workspaces.create(jwt: jwt, name: "Acme Corp")
+
+# List
+workspaces = client.workspaces.list(jwt: jwt)
+
+# Get details (includes members)
+ws = client.workspaces.get(jwt: jwt, workspace_id: workspace["id"])
+
+# Invite a member
+client.workspaces.invite(
+  jwt:          jwt,
+  workspace_id: workspace["id"],
+  email:        "colleague@example.com",
+  role:         "member"   # "admin" | "member" | "viewer"
+)
+
+# Change role
+client.workspaces.update_member(
+  jwt:          jwt,
+  workspace_id: workspace["id"],
+  user_id:      "usr_abc",
+  role:         "admin"
+)
+
+# Remove member
+client.workspaces.remove_member(
+  jwt:          jwt,
+  workspace_id: workspace["id"],
+  user_id:      "usr_abc"
+)
+```
+
+---
+
+## App Monitors
+
+```ruby
+jwt = client.auth.token(email: "you@example.com", password: "secret")["token"]
+
+# Create a monitor — runs daily at 9 AM UTC
+monitor = client.monitors.create(
+  jwt:         jwt,
+  app_name:    "Spotify",
+  platform:    "both",
+  schedule:    "0 9 * * *",
+  webhook_url: "https://yourapp.com/webhooks/monitor"
+)
+
+# List
+client.monitors.list(jwt: jwt)
+
+# Get
+client.monitors.get(jwt: jwt, monitor_id: monitor["id"])
+
+# Run history (last 20 entries)
+history = client.monitors.history(jwt: jwt, monitor_id: monitor["id"], limit: 20)
+
+# Delete
+client.monitors.delete(jwt: jwt, monitor_id: monitor["id"])
+```
+
+---
+
+## Zapier Integration
+
+```ruby
+# Subscribe (register a webhook for a Zapier trigger)
+sub = client.integrations.zapier_subscribe(
+  target_url: "https://hooks.zapier.com/hooks/catch/...",
+  event:      "screenshot.completed"
+)
+
+# Sample payload for Zap editor
+sample = client.integrations.zapier_triggers(event: "screenshot.completed")
+
+# Unsubscribe
+client.integrations.zapier_unsubscribe(subscription_id: sub["id"])
+```
+
+---
+
+## Webhook Verification
+
+ScreenshotFreeAPI signs all webhook payloads using HMAC-SHA256. Always verify the
+signature before processing the event.
+
+```ruby
+# Standalone verification
+require "screenshotfreeapi"
+
+raw_body  = request.body.read   # raw bytes — do NOT parse yet
+signature = request.headers["X-ScreenshotFree-Signature"]
+secret    = ENV["SCREENSHOTFREEAPI_WEBHOOK_SECRET"]
+
+unless ScreenshotFreeAPI::Webhooks.verify_signature(raw_body, signature, secret)
+  render plain: "Invalid signature", status: :forbidden
+  return
+end
+
+event = JSON.parse(raw_body)
+puts event["status"]  # "completed" | "failed"
+
+# Or use construct_event (raises ArgumentError on bad signature):
+begin
+  event = ScreenshotFreeAPI::Webhooks.construct_event(raw_body, signature, secret)
+rescue ArgumentError => e
+  render plain: e.message, status: :forbidden
+  return
+end
+```
+
+---
+
+## Rails Integration
+
+Create an initializer `config/initializers/screenshotfreeapi.rb`:
+
+```ruby
+require "screenshotfreeapi"
+
+SCREENSHOTFREEAPI_CLIENT = ScreenshotFreeAPI.new(
+  api_key:     Rails.application.credentials.screenshotfreeapi_key!,
+  timeout:     45,
+  max_retries: 3
+)
+```
+
+Then use `SCREENSHOTFREEAPI_CLIENT` anywhere in your application:
+
+```ruby
+class ScreenshotJob < ApplicationJob
+  def perform(url)
+    result = SCREENSHOTFREEAPI_CLIENT.capture(url, format: "png", full_page: true)
+    url    = result["screenshots"].first["url"]
+    Rails.logger.info "Screenshot ready: #{url}"
+  end
+end
+```
+
+---
+
+## Configuration Reference
+
+| Option        | Type    | Default                        | Description                          |
+|---------------|---------|--------------------------------|--------------------------------------|
+| `api_key`     | String  | required                       | Your ScreenshotFreeAPI key (`sfa_...`)    |
+| `base_url`    | String  | `https://api.screenshotfreeapi.com`     | Override for staging / local dev     |
+| `timeout`     | Integer | `30`                           | HTTP open/read timeout (seconds)     |
+| `max_retries` | Integer | `3`                            | Retries on 429 and 5xx errors        |
+
+---
+
+## License
+
+MIT — see LICENSE file.

data/lib/screenshotfreeapi/client.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ScreenshotFreeAPI
+  # Main entry point for the ScreenshotFreeAPI Ruby SDK.
+  #
+  # Instantiate once (e.g., in a Rails initializer) and reuse across requests.
+  # All resource objects share the same underlying HttpClient instance.
+  #
+  # Quick start:
+  #
+  #   client = ScreenshotFreeAPI::Client.new(api_key: ENV["SCREENSHOTFREEAPI_KEY"])
+  #   result = client.capture("https://stripe.com", format: "png")
+  #   puts result["screenshots"].first["url"]
+  #
+  class Client
+    attr_reader :screenshots, :jobs, :auth, :billing, :workspaces, :monitors, :integrations
+
+    # @param api_key      [String]  Your ScreenshotFreeAPI key (sfa_...)
+    # @param base_url     [String]  Override base URL for staging / local dev
+    # @param timeout      [Integer] HTTP open/read timeout in seconds (default: 30)
+    # @param max_retries  [Integer] Max retry attempts on 429 / 5xx (default: 3)
+    def initialize(
+      api_key:,
+      base_url:    HttpClient::DEFAULT_BASE_URL,
+      timeout:     HttpClient::DEFAULT_TIMEOUT,
+      max_retries: HttpClient::DEFAULT_RETRIES
+    )
+      @http = HttpClient.new(
+        api_key:     api_key,
+        base_url:    base_url,
+        timeout:     timeout,
+        max_retries: max_retries
+      )
+
+      @screenshots  = Resources::Screenshots.new(@http)
+      @jobs         = Resources::Jobs.new(@http)
+      @auth         = Resources::Auth.new(@http)
+      @billing      = Resources::Billing.new(@http)
+      @workspaces   = Resources::Workspaces.new(@http)
+      @monitors     = Resources::Monitors.new(@http)
+      @integrations = Resources::Integrations.new(@http)
+    end
+
+    # Convenience method: capture a URL and wait for the result.
+    #
+    # Equivalent to `client.screenshots.web_and_wait({ url: url }.merge(opts))`.
+    #
+    # @param url           [String]  URL to capture
+    # @param poll_interval [Numeric] Seconds between status polls (default: 2)
+    # @param timeout       [Numeric] Maximum seconds to wait (default: 120)
+    # @param opts          [Hash]    Any additional web screenshot options
+    # @yieldparam status   [Hash]    Progress callback, called on each poll
+    #
+    # @return [Hash] Full result hash with "screenshots" array
+    def capture(url, poll_interval: 2, timeout: 120, **opts, &on_progress)
+      options = { url: url }.merge(opts)
+      @screenshots.web_and_wait(options, poll_interval: poll_interval, timeout: timeout, &on_progress)
+    end
+
+    # Check API health (no authentication required).
+    #
+    # @return [Hash] { "status" => "ok", "version" => "..." }
+    def health
+      @http.request(:get, "/health", auth_header: "")
+    end
+  end
+end

data/lib/screenshotfreeapi/errors.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ScreenshotFreeAPI
+  # Base error class for all ScreenshotFreeAPI errors that originate from HTTP responses.
+  class ScreenshotFreeAPIError < StandardError
+    attr_reader :status_code, :error_code, :details
+
+    def initialize(status_code, error_code, message, details = nil)
+      super(message)
+      @status_code  = status_code
+      @error_code   = error_code
+      @details      = details
+    end
+  end
+
+  # 401 — Invalid or missing API key / JWT.
+  class AuthenticationError < ScreenshotFreeAPIError
+    def initialize(msg = "Invalid or missing API key")
+      super(401, "Unauthorized", msg)
+    end
+  end
+
+  # 403 — API key revoked or account suspended.
+  class ForbiddenError < ScreenshotFreeAPIError
+    def initialize(msg = "Access forbidden")
+      super(403, "Forbidden", msg)
+    end
+  end
+
+  # 404 — Resource not found or not owned by this key.
+  class NotFoundError < ScreenshotFreeAPIError
+    def initialize(msg = "Resource not found")
+      super(404, "NotFound", msg)
+    end
+  end
+
+  # 400 — Request body failed Zod validation on the server.
+  class ValidationError < ScreenshotFreeAPIError
+    def initialize(msg = "Validation error", details = nil)
+      super(400, "ValidationError", msg, details)
+    end
+  end
+
+  # 402 — Subscription cancelled or payment overdue.
+  class PaymentRequiredError < ScreenshotFreeAPIError
+    def initialize(msg = "Payment required — subscription cancelled or payment overdue")
+      super(402, "PaymentRequired", msg)
+    end
+  end
+
+  # 429 — Per-minute rate limit exceeded. Includes `retry_after` seconds.
+  class RateLimitError < ScreenshotFreeAPIError
+    attr_reader :retry_after
+
+    def initialize(retry_after = nil, msg = "Rate limit exceeded")
+      super(429, "RateLimitExceeded", msg)
+      @retry_after = retry_after
+    end
+  end
+
+  # 429 with quota body — monthly screenshot quota exhausted.
+  class QuotaExceededError < ScreenshotFreeAPIError
+    def initialize(msg = "Monthly screenshot quota exceeded")
+      super(429, "QuotaExceeded", msg)
+    end
+  end
+
+  # Raised when polling a job that has transitioned to the FAILED state.
+  class JobFailedError < StandardError
+    attr_reader :job_id, :reason
+
+    def initialize(job_id, reason)
+      super("Job #{job_id} failed: #{reason}")
+      @job_id  = job_id
+      @reason  = reason
+    end
+  end
+
+  # Raised when a job does not complete within the configured polling timeout.
+  class JobTimeoutError < StandardError
+    attr_reader :job_id, :timeout_seconds
+
+    def initialize(job_id, timeout_seconds)
+      super("Job #{job_id} did not complete within #{timeout_seconds}s")
+      @job_id          = job_id
+      @timeout_seconds = timeout_seconds
+    end
+  end
+end