renderscreenshot 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 866ece0d8812f0d70751db71d9746530c4e4b0f95a39624f569672b93688137b
+  data.tar.gz: a6d705614f59526337dc55e852075ed21030f66e2a71c17a94895db00386993a
+SHA512:
+  metadata.gz: f8a11440d6feb0739526fe945732ed2c12e0e0130476c48b6c96d544d98fa70b41c1a9d982e621a42046f42cf0d2bd4b8ffe2d1ef2c618163318a8a4e3b3355d
+  data.tar.gz: 11cc424b00ae6727181f580118644a01aa2bb29ddf7554d8a8768e7ebf6bdf410cf862b8728abee757d6d484f30d76fd7f0973ff8e4b31a349249579f1885d48

data/.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+repos:
+  # Secret detection - Gitleaks
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  # Secret detection - detect-secrets (additional layer)
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.4.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: vendor/
+
+  # General checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-json
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: no-commit-to-branch
+        args: ['--branch', 'main']
+
+  # Ruby linting
+  - repo: local
+    hooks:
+      - id: rubocop
+        name: RuboCop
+        entry: bundle exec rubocop --force-exclusion
+        language: system
+        types: [ruby]
+        pass_filenames: true

data/.rubocop.yml

@@ -0,0 +1,86 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - '*.gemspec'
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+# SDK pattern: boolean defaults are common for fluent builders
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+# SDK pattern: memoization with descriptive names
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+# Private methods can have short parameter names
+Naming/MethodParameterName:
+  Enabled: false
+
+# Predicate methods in private scope
+Naming/PredicateMethod:
+  Enabled: false
+
+# Allow HTTP status codes in test method names
+Naming/VariableNumber:
+  CheckMethodNames: false
+
+# Allow mutable constants for dynamic values
+Style/MutableConstant:
+  Enabled: false
+
+# Duplicate branches are intentional for error mapping
+Lint/DuplicateBranch:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'test/**/*'
+    - 'Rakefile'
+
+Metrics/MethodLength:
+  Max: 30
+  Exclude:
+    - 'lib/renderscreenshot/take_options.rb'
+    - 'test/**/*'
+
+Metrics/AbcSize:
+  Max: 50
+  Exclude:
+    - 'lib/renderscreenshot/take_options.rb'
+    - 'test/**/*'
+
+Metrics/ClassLength:
+  Max: 300
+  Exclude:
+    - 'lib/renderscreenshot/take_options.rb'
+    - 'test/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+  Exclude:
+    - 'lib/renderscreenshot/take_options.rb'
+
+Metrics/PerceivedComplexity:
+  Max: 15
+  Exclude:
+    - 'lib/renderscreenshot/take_options.rb'
+
+Metrics/ParameterLists:
+  Max: 7
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'test/**/*'

data/.secrets.baseline

@@ -0,0 +1,116 @@
+{
+  "version": "1.4.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_baseline_file",
+      "filename": ".secrets.baseline"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {},
+  "generated_at": "2025-01-31T00:00:00Z"
+}

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-02-24
+
+### Added
+
+- Initial release of the RenderScreenshot Ruby SDK
+- `Client` class for API interactions
+  - `take` - Get screenshot as binary data
+  - `take_json` - Get screenshot with JSON metadata
+  - `generate_url` - Create signed URLs
+  - `batch` - Batch process multiple URLs
+  - `batch_advanced` - Batch with per-URL options
+  - `get_batch` - Check batch status
+  - `presets` - List available presets
+  - `preset` - Get specific preset
+  - `devices` - List device presets
+  - `cache` - Access cache manager
+- `TakeOptions` fluent builder with 58+ methods
+  - Viewport: `width`, `height`, `scale`, `mobile`
+  - Capture: `full_page`, `element`, `format`, `quality`
+  - Wait: `wait_for`, `delay`, `wait_for_selector`, `wait_for_timeout`
+  - Presets: `preset`, `device`
+  - Blocking: `block_ads`, `block_trackers`, `block_cookie_banners`, `block_chat_widgets`, `block_urls`, `block_resources`
+  - Page: `inject_script`, `inject_style`, `click`, `hide`, `remove`
+  - Browser: `dark_mode`, `reduced_motion`, `media_type`, `user_agent`, `timezone`, `locale`, `geolocation`
+  - Network: `headers`, `cookies`, `auth_basic`, `auth_bearer`, `bypass_csp`
+  - Cache: `cache_ttl`, `cache_refresh`
+  - PDF: All PDF-specific options
+  - Storage: `storage_enabled`, `storage_path`, `storage_acl`
+- `CacheManager` for cache operations
+  - `get`, `delete`, `purge`, `purge_url`, `purge_before`, `purge_pattern`
+- `Webhook` module for webhook verification
+  - `verify` - HMAC-SHA256 signature verification
+  - `parse` - Parse webhook payload
+  - `extract_headers` - Extract signature/timestamp from headers
+- Error hierarchy with `retryable?` support
+  - `ValidationError`, `AuthenticationError`, `AuthorizationError`
+  - `NotFoundError`, `RateLimitError`, `TimeoutError`
+  - `ServerError`, `ConnectionError`
+- Global configuration via `RenderScreenshot.configure`
+- Dependabot for automated dependency updates
+- Full test coverage with Minitest (142 tests, 97% coverage)
+
+### Security
+
+- Faraday minimum version set to >= 2.12.3 (AIKIDO-2025-10223 vulnerability in earlier versions)
+
+### Requirements
+
+- Ruby >= 3.2.0
+- Faraday >= 2.12.3, < 3.0
+
+[1.0.0]: https://github.com/Render-Screenshot/rs-ruby/releases/tag/v1.0.0

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'bundler-audit', '~> 0.9'
+  gem 'minitest', '~> 5.20'
+  gem 'minitest-reporters', '~> 1.6'
+  gem 'rake', '~> 13.0'
+  gem 'rubocop', '~> 1.70'
+  gem 'simplecov', '~> 0.22', require: false
+  gem 'timecop', '~> 0.9'
+  gem 'webmock', '~> 3.18'
+  gem 'yard', '~> 0.9'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RenderScreenshot
+
+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,356 @@
+# RenderScreenshot Ruby SDK
+
+The official Ruby SDK for [RenderScreenshot](https://renderscreenshot.com) - a developer-friendly screenshot API for capturing web pages programmatically.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'renderscreenshot'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install renderscreenshot
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+
+## Quick Start
+
+```ruby
+require 'renderscreenshot'
+
+# Create a client
+client = RenderScreenshot.client('rs_live_your_api_key')
+
+# Take a screenshot
+image_data = client.take(
+  RenderScreenshot::TakeOptions
+    .url('https://example.com')
+    .width(1200)
+    .height(630)
+    .format('png')
+)
+
+# Save to file
+File.binwrite('screenshot.png', image_data)
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+RenderScreenshot.configure do |config|
+  config.base_url = 'https://api.renderscreenshot.com'  # Default
+  config.timeout = 30  # Default timeout in seconds
+end
+```
+
+### Per-Client Configuration
+
+```ruby
+client = RenderScreenshot.client(
+  'rs_live_your_api_key',
+  base_url: 'https://custom.api.com',
+  timeout: 60
+)
+```
+
+## Usage
+
+### Taking Screenshots
+
+#### Binary Response
+
+```ruby
+# Get screenshot as binary data
+image_data = client.take(
+  RenderScreenshot::TakeOptions
+    .url('https://example.com')
+    .preset('og_card')
+)
+```
+
+#### JSON Response (with metadata)
+
+```ruby
+# Get screenshot URL and metadata
+response = client.take_json(
+  RenderScreenshot::TakeOptions
+    .url('https://example.com')
+    .preset('og_card')
+)
+
+puts response['image']['url']      # CDN URL
+puts response['image']['width']    # 1200
+puts response['image']['height']   # 630
+puts response['cache']['key']      # Cache key for later reference
+```
+
+### Screenshot Options
+
+The `TakeOptions` class provides a fluent interface for configuring screenshots:
+
+```ruby
+options = RenderScreenshot::TakeOptions
+  .url('https://example.com')
+  # Viewport
+  .width(1920)
+  .height(1080)
+  .scale(2)
+  .mobile(true)
+  # Capture
+  .full_page
+  .element('#main-content')
+  .format('webp')
+  .quality(90)
+  # Wait conditions
+  .wait_for('networkidle')
+  .delay(500)
+  .wait_for_selector('.loaded')
+  # Blocking
+  .block_ads
+  .block_trackers
+  .block_cookie_banners
+  # Browser emulation
+  .dark_mode
+  .timezone('America/New_York')
+  .locale('en-US')
+```
+
+### Using Presets
+
+```ruby
+# Social card presets
+options = RenderScreenshot::TakeOptions
+  .url('https://example.com')
+  .preset('og_card')  # 1200x630 for Open Graph
+
+# Device presets
+options = RenderScreenshot::TakeOptions
+  .url('https://example.com')
+  .device('iphone_14_pro')
+```
+
+### PDF Generation
+
+```ruby
+options = RenderScreenshot::TakeOptions
+  .url('https://example.com')
+  .format('pdf')
+  .pdf_paper_size('a4')
+  .pdf_landscape
+  .pdf_print_background
+  .pdf_margin('1cm')
+
+pdf_data = client.take(options)
+File.binwrite('document.pdf', pdf_data)
+```
+
+### Batch Processing
+
+```ruby
+# Simple batch (same options for all URLs)
+response = client.batch(
+  ['https://example1.com', 'https://example2.com', 'https://example3.com'],
+  options: RenderScreenshot::TakeOptions.url('').preset('og_card')
+)
+
+response['results'].each do |result|
+  puts "#{result['url']}: #{result['status']}"
+end
+
+# Advanced batch (per-URL options)
+response = client.batch_advanced([
+  { url: 'https://example1.com', options: { preset: 'og_card' } },
+  { url: 'https://example2.com', options: { preset: 'twitter_card' } }
+])
+```
+
+### Signed URLs
+
+Generate signed URLs for client-side use without exposing your API key:
+
+```ruby
+options = RenderScreenshot::TakeOptions
+  .url('https://example.com')
+  .preset('og_card')
+
+# URL expires in 24 hours
+signed_url = client.generate_url(options, expires_at: Time.now + 86400)
+
+# Use in HTML
+# <img src="#{signed_url}" />
+```
+
+### Cache Management
+
+```ruby
+cache = client.cache
+
+# Get cached screenshot
+data = cache.get('cache_key_123')
+
+# Delete cached entry
+cache.delete('cache_key_123')
+
+# Bulk purge
+cache.purge(['key1', 'key2', 'key3'])
+
+# Purge by URL pattern
+cache.purge_url('https://example.com/*')
+
+# Purge by date
+cache.purge_before(Time.now - 86400 * 7)  # Older than 7 days
+
+# Purge by storage path pattern
+cache.purge_pattern('screenshots/2024/01/*')
+```
+
+### Presets and Devices
+
+```ruby
+# List all presets
+presets = client.presets
+presets.each { |p| puts "#{p['id']}: #{p['name']}" }
+
+# Get specific preset
+preset = client.preset('og_card')
+
+# List all devices
+devices = client.devices
+devices.each { |d| puts "#{d['id']}: #{d['name']} (#{d['width']}x#{d['height']})" }
+```
+
+### Webhook Verification
+
+```ruby
+# In your webhook endpoint
+def webhook_handler(request)
+  payload = request.body.read
+  signature, timestamp = RenderScreenshot::Webhook.extract_headers(request.headers)
+
+  unless RenderScreenshot::Webhook.verify(
+    payload: payload,
+    signature: signature,
+    timestamp: timestamp,
+    secret: ENV['WEBHOOK_SECRET']
+  )
+    return [401, 'Invalid signature']
+  end
+
+  event = RenderScreenshot::Webhook.parse(payload)
+
+  case event[:event]
+  when 'screenshot.completed'
+    handle_screenshot_completed(event[:data])
+  when 'screenshot.failed'
+    handle_screenshot_failed(event[:data])
+  when 'batch.completed'
+    handle_batch_completed(event[:data])
+  end
+
+  [200, 'OK']
+end
+```
+
+## Error Handling
+
+All API errors inherit from `RenderScreenshot::Error`:
+
+```ruby
+begin
+  client.take(RenderScreenshot::TakeOptions.url('https://example.com'))
+rescue RenderScreenshot::ValidationError => e
+  puts "Invalid request: #{e.message}"
+rescue RenderScreenshot::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue RenderScreenshot::RateLimitError => e
+  puts "Rate limited. Retry after #{e.retry_after} seconds"
+  sleep(e.retry_after) if e.retry_after
+  retry
+rescue RenderScreenshot::TimeoutError => e
+  puts "Request timed out" if e.retryable?
+rescue RenderScreenshot::ServerError => e
+  puts "Server error: #{e.message}"
+  retry if e.retryable?
+rescue RenderScreenshot::ConnectionError => e
+  puts "Connection failed: #{e.message}"
+end
+```
+
+Error properties:
+- `http_status` - HTTP status code
+- `code` - Error code from API
+- `message` - Human-readable message
+- `request_id` - Request ID for support
+- `retry_after` - Seconds to wait (rate limits)
+- `retryable?` - Whether the error can be retried
+
+## Complete Options Reference
+
+| Category | Methods |
+|----------|---------|
+| **Viewport** | `width`, `height`, `scale`, `mobile` |
+| **Capture** | `full_page`, `element`, `format`, `quality` |
+| **Wait** | `wait_for`, `delay`, `wait_for_selector`, `wait_for_timeout` |
+| **Preset** | `preset`, `device` |
+| **Blocking** | `block_ads`, `block_trackers`, `block_cookie_banners`, `block_chat_widgets`, `block_urls`, `block_resources` |
+| **Page** | `inject_script`, `inject_style`, `click`, `hide`, `remove` |
+| **Browser** | `dark_mode`, `reduced_motion`, `media_type`, `user_agent`, `timezone`, `locale`, `geolocation` |
+| **Network** | `headers`, `cookies`, `auth_basic`, `auth_bearer`, `bypass_csp` |
+| **Cache** | `cache_ttl`, `cache_refresh` |
+| **PDF** | `pdf_paper_size`, `pdf_width`, `pdf_height`, `pdf_landscape`, `pdf_margin`, `pdf_margin_top`, `pdf_margin_right`, `pdf_margin_bottom`, `pdf_margin_left`, `pdf_scale`, `pdf_print_background`, `pdf_page_ranges`, `pdf_header`, `pdf_footer`, `pdf_fit_one_page`, `pdf_prefer_css_page_size` |
+| **Storage** | `storage_enabled`, `storage_path`, `storage_acl` |
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+bundle exec rake test      # Run tests
+bundle exec rubocop        # Run linter
+bundle exec rake           # Run both
+```
+
+### Pre-commit Hooks
+
+This project uses pre-commit hooks to prevent secrets from being committed:
+
+```bash
+# Install pre-commit (if not already installed)
+brew install pre-commit    # macOS
+pip install pre-commit     # or via pip
+
+# Install the hooks
+pre-commit install
+
+# Run manually on all files
+pre-commit run --all-files
+```
+
+The hooks include:
+- **Gitleaks** - Scans for secrets and API keys
+- **detect-private-key** - Prevents committing private keys
+- **check-added-large-files** - Prevents large files (>500KB)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/renderscreenshot/renderscreenshot-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).