screenshotfreeapi 1.0.0

data/lib/screenshotfreeapi/resources/workspaces.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ScreenshotFreeAPI
+  module Resources
+    # Team workspace management.
+    #
+    # Workspaces allow multiple users to share API keys and collaborate.
+    # All methods require a management JWT (from Auth#token) passed as `jwt:`.
+    #
+    # Member roles: "owner" | "admin" | "member" | "viewer"
+    class Workspaces
+      def initialize(http)
+        @http = http
+      end
+
+      # Create a new workspace.
+      #
+      # @param jwt  [String] Management JWT
+      # @param name [String] Workspace display name
+      #
+      # @return [Hash] Workspace object
+      def create(jwt:, name:, **options)
+        body = { name: name }.merge(options)
+        @http.request(:post, "/workspaces", body: body, auth_header: "Bearer #{jwt}")
+      end
+
+      # List workspaces the authenticated user belongs to.
+      #
+      # @param jwt [String] Management JWT
+      #
+      # @return [Array<Hash>] Array of workspace objects
+      def list(jwt:)
+        @http.request(:get, "/workspaces", auth_header: "Bearer #{jwt}")
+      end
+
+      # Get a single workspace with its members list.
+      #
+      # @param jwt          [String] Management JWT
+      # @param workspace_id [String] Workspace ID
+      #
+      # @return [Hash] Workspace object including "members" array
+      def get(jwt:, workspace_id:)
+        @http.request(:get, "/workspaces/#{workspace_id}", auth_header: "Bearer #{jwt}")
+      end
+
+      # Invite a user to the workspace by email address.
+      #
+      # @param jwt          [String]
+      # @param workspace_id [String]
+      # @param email        [String] Email of the person to invite
+      # @param role         [String] "admin" | "member" | "viewer"
+      #
+      # @return [Hash] Invitation object
+      def invite(jwt:, workspace_id:, email:, role: "member")
+        @http.request(
+          :post,
+          "/workspaces/#{workspace_id}/invite",
+          body:        { email: email, role: role },
+          auth_header: "Bearer #{jwt}"
+        )
+      end
+
+      # Remove a member from the workspace.
+      #
+      # @param jwt          [String]
+      # @param workspace_id [String]
+      # @param user_id      [String] ID of the member to remove
+      #
+      # @return [Hash] Confirmation object
+      def remove_member(jwt:, workspace_id:, user_id:)
+        @http.request(
+          :delete,
+          "/workspaces/#{workspace_id}/members/#{user_id}",
+          auth_header: "Bearer #{jwt}"
+        )
+      end
+
+      # Change a member's role within the workspace.
+      #
+      # @param jwt          [String]
+      # @param workspace_id [String]
+      # @param user_id      [String]
+      # @param role         [String] New role: "admin" | "member" | "viewer"
+      #
+      # @return [Hash] Updated member object
+      def update_member(jwt:, workspace_id:, user_id:, role:)
+        @http.request(
+          :patch,
+          "/workspaces/#{workspace_id}/members/#{user_id}",
+          body:        { role: role },
+          auth_header: "Bearer #{jwt}"
+        )
+      end
+    end
+  end
+end

data/lib/screenshotfreeapi/version.rb

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

data/lib/screenshotfreeapi/webhooks.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module ScreenshotFreeAPI
+  # Utilities for verifying incoming ScreenshotFreeAPI webhook signatures.
+  #
+  # The API signs webhook payloads with HMAC-SHA256 using your webhook secret.
+  # The signature is delivered in the `X-ScreenshotFree-Signature` header as a hex digest.
+  #
+  # Example (Rack / Rails):
+  #
+  #   raw_body  = request.body.read
+  #   signature = request.headers["X-ScreenshotFree-Signature"]
+  #
+  #   unless ScreenshotFreeAPI::Webhooks.verify_signature(raw_body, signature, ENV["WEBHOOK_SECRET"])
+  #     render plain: "Bad signature", status: :forbidden and return
+  #   end
+  #
+  module Webhooks
+    # Verify that a webhook payload was signed by the ScreenshotFreeAPI.
+    #
+    # Uses a constant-time comparison to prevent timing attacks.
+    #
+    # @param raw_body  [String]  Raw request body bytes (before any parsing)
+    # @param signature [String]  Value of the `X-ScreenshotFree-Signature` header
+    # @param secret    [String]  Your webhook signing secret
+    #
+    # @return [Boolean] `true` if the signature is valid, `false` otherwise
+    def self.verify_signature(raw_body, signature, secret)
+      return false if raw_body.nil? || signature.nil? || secret.nil?
+      return false if signature.empty? || secret.empty?
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, raw_body.to_s)
+      secure_compare(expected, signature.to_s)
+    end
+
+    # Parse a verified webhook payload into a plain hash.
+    #
+    # Raises ArgumentError if the signature is invalid.
+    #
+    # @param raw_body  [String] Raw request body
+    # @param signature [String] X-ScreenshotFree-Signature header value
+    # @param secret    [String] Webhook signing secret
+    #
+    # @return [Hash] Parsed event payload
+    def self.construct_event(raw_body, signature, secret)
+      unless verify_signature(raw_body, signature, secret)
+        raise ArgumentError, "Invalid webhook signature"
+      end
+
+      require "json"
+      JSON.parse(raw_body)
+    end
+
+    # Constant-time string comparison to mitigate timing side-channel attacks.
+    #
+    # XORs each byte of both strings and accumulates any differences.
+    # Returns true only when the accumulated diff is zero (all bytes equal)
+    # and both strings have the same length.
+    #
+    # @param a [String] First string (expected)
+    # @param b [String] Second string (provided)
+    # @return [Boolean]
+    def self.secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack("C#{a.bytesize}")
+      r = b.unpack("C#{b.bytesize}")
+
+      diff = 0
+      l.zip(r) { |x, y| diff |= (x ^ y) }
+      diff.zero?
+    end
+
+    private_class_method :secure_compare
+  end
+end

data/lib/screenshotfreeapi.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# screenshotfreeapi — Official Ruby SDK for ScreenshotFreeAPI
+#
+# ScreenshotFreeAPI is a screenshot-as-a-service platform. This SDK wraps the
+# REST API and provides a clean Ruby interface for capturing web pages,
+# mobile app store listings, and HTML strings.
+#
+# Quick start:
+#
+#   require "screenshotfreeapi"
+#
+#   client = ScreenshotFreeAPI.new(api_key: ENV["SCREENSHOTFREEAPI_KEY"])
+#   result = client.capture("https://example.com")
+#   puts result["screenshots"].first["url"]
+#
+
+require_relative "screenshotfreeapi/version"
+require_relative "screenshotfreeapi/errors"
+require_relative "screenshotfreeapi/http_client"
+require_relative "screenshotfreeapi/webhooks"
+require_relative "screenshotfreeapi/resources/auth"
+require_relative "screenshotfreeapi/resources/jobs"
+require_relative "screenshotfreeapi/resources/screenshots"
+require_relative "screenshotfreeapi/resources/billing"
+require_relative "screenshotfreeapi/resources/workspaces"
+require_relative "screenshotfreeapi/resources/monitors"
+require_relative "screenshotfreeapi/resources/integrations"
+require_relative "screenshotfreeapi/client"
+
+module ScreenshotFreeAPI
+  # Convenience constructor — creates a Client without needing to reference
+  # the full class path.
+  #
+  # @param api_key     [String]
+  # @param base_url    [String]  (optional)
+  # @param timeout     [Integer] (optional)
+  # @param max_retries [Integer] (optional)
+  #
+  # @return [ScreenshotFreeAPI::Client]
+  #
+  # @example
+  #   client = ScreenshotFreeAPI.new(api_key: "sfa_...")
+  def self.new(api_key:, **opts)
+    Client.new(api_key: api_key, **opts)
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: screenshotfreeapi
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ScreenshotFreeAPI
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-20 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client for ScreenshotFreeAPI — screenshot-as-a-service. Capture
+  web pages, mobile app store listings, and HTML strings via a simple HTTP API. Supports
+  async job polling, webhook signature verification, and all billing/workspace endpoints.
+email:
+- support@screenshotfreeapi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/screenshotfreeapi.rb
+- lib/screenshotfreeapi/client.rb
+- lib/screenshotfreeapi/errors.rb
+- lib/screenshotfreeapi/http_client.rb
+- lib/screenshotfreeapi/resources/auth.rb
+- lib/screenshotfreeapi/resources/billing.rb
+- lib/screenshotfreeapi/resources/integrations.rb
+- lib/screenshotfreeapi/resources/jobs.rb
+- lib/screenshotfreeapi/resources/monitors.rb
+- lib/screenshotfreeapi/resources/screenshots.rb
+- lib/screenshotfreeapi/resources/workspaces.rb
+- lib/screenshotfreeapi/version.rb
+- lib/screenshotfreeapi/webhooks.rb
+homepage: https://api.screenshotfreeapi.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://api.screenshotfreeapi.com
+  source_code_uri: https://github.com/chinkauchenna2021/screenshotfreeapi-ruby
+  changelog_uri: https://github.com/chinkauchenna2021/screenshotfreeapi-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/chinkauchenna2021/screenshotfreeapi-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for ScreenshotFreeAPI
+test_files: []