zyterb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e61dfe9e5c35f4915994e9bf59bbf3813d3b662da563e97442a23bb6ae8bc9b7
+  data.tar.gz: 95bfa6302732227afa6140b88463049de35b175dfbcecfed89854baa1bd2c53c
+SHA512:
+  metadata.gz: 60c991c67b8e5ca891e4986b0f5488ccb623171b7c9f1809d5de627df2160df813a42ce9481b1ff852415d034210184517f68244f44013e1794138a796d4ba63
+  data.tar.gz: 1cc581b173eeb7babb867ded4a30cdd30dd88c0a851d79eacbf88bd52e2ce05869f204fa64841263e86c427f64aed09e1e5bdd739cc64b44b3083574a3f42943

data/README.md

@@ -0,0 +1,86 @@
+# Zyterb
+
+A zero-dependency Ruby client for the [Zyte API](https://docs.zyte.com/zyte-api/usage/reference.html). It uses only Ruby's standard library (`Net::HTTP`, `JSON`, `Base64`).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zyterb'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install zyterb
+
+## Usage
+
+### Configuration
+
+You can provide your Zyte API key via an environment variable:
+
+```bash
+export ZYTE_API_KEY='your_api_key_here'
+```
+
+Or via a configuration block:
+
+```ruby
+require 'zyterb'
+
+Zyterb.configure do |config|
+  config.api_key = 'your_api_key_here'
+end
+
+client = Zyterb::Client.new
+```
+
+Or pass it when initializing the client:
+
+```ruby
+client = Zyterb::Client.new(api_key: 'your_api_key_here')
+```
+
+### Basic Extraction
+
+By default, it fetches `browserHtml`:
+
+```ruby
+result = client.extract("https://example.com")
+puts result['browserHtml']
+```
+
+### AI Structured Extraction
+
+Zyte API supports AI-driven extraction for specific page types:
+
+```ruby
+# Extract an article
+article = client.extract("https://example.com/blog/post", article: true)
+puts article['article']['headline']
+
+# Extract a product
+product = client.extract("https://example.com/p/123", product: true)
+puts product['product']['name']
+```
+
+Supported AI fields include: `article`, `product`, `jobPosting`, `serp`, and more.
+
+### Screenshots
+
+The `#screenshot` method returns the raw binary image data (it handles Base64 decoding for you).
+
+```ruby
+image_data = client.screenshot("https://example.com", format: 'png', full_page: true)
+
+File.binwrite("example.png", image_data)
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/zyterb/client.rb

@@ -0,0 +1,116 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'base64'
+require 'zlib'
+require 'stringio'
+
+module Zyterb
+  class Client
+    API_URL = "https://api.zyte.com/v1/extract".freeze
+    
+    # List of known Zyte AI extraction fields
+    AI_FIELDS = [
+      :article, :articleList, :articleNavigation,
+      :product, :productList, :productNavigation,
+      :jobPosting, :jobPostingNavigation,
+      :forumThread, :pageContent, :serp
+    ].freeze
+
+    attr_reader :api_key
+
+    def initialize(api_key: nil)
+      @api_key = api_key || ENV['ZYTE_API_KEY'] || Zyterb.configuration.api_key
+      raise ArgumentError, "API key is required. Set ENV['ZYTE_API_KEY'], use Zyterb.configure, or pass it to Client.new" if @api_key.nil? || @api_key.empty?
+    end
+
+    # Extract data from a URL.
+    # @param url [String] The URL to extract data from.
+    # @param options [Hash] Additional options for Zyte API (e.g., article: true, browserHtml: true).
+    # @return [Hash] The parsed JSON response from Zyte.
+    def extract(url, options = {})
+      payload = { url: url }.merge(options)
+      
+      # Default to browserHtml if no specific extraction type is requested
+      extraction_keys = [:browserHtml, :httpResponseBody, :screenshot] + AI_FIELDS
+      if (payload.keys & extraction_keys).empty?
+        payload[:browserHtml] = true
+      end
+
+      response = request(payload)
+      parse_response(response)
+    end
+
+    # Take a screenshot of a URL.
+    # @param url [String] The URL to screenshot.
+    # @param format [String] 'png' (default) or 'jpeg'.
+    # @param full_page [Boolean] Capture the full page or just the viewport.
+    # @param options [Hash] Additional options to merge into the payload.
+    # @return [String] The raw binary image data.
+    def screenshot(url, format: 'png', full_page: false, options: {})
+      payload = {
+        url: url,
+        screenshot: true,
+        screenshotOptions: { format: format, fullPage: full_page }
+      }.merge(options)
+      
+      response = request(payload)
+      parsed = parse_response(response)
+      
+      if parsed['screenshot']
+        Base64.decode64(parsed['screenshot'])
+      else
+        raise Error, "No screenshot returned from Zyte API"
+      end
+    end
+
+    private
+
+    def request(payload)
+      uri = URI.parse(API_URL)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = 180
+      http.open_timeout = 180
+
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req.basic_auth(@api_key, "")
+      req['Content-Type'] = 'application/json'
+      req['Accept-Encoding'] = 'gzip, deflate'
+      req.body = JSON.generate(payload)
+
+      http.request(req)
+    end
+
+    def parse_response(response)
+      body = response.body
+      
+      if response['Content-Encoding'] == 'gzip' && body && !body.empty?
+        begin
+          body = Zlib::GzipReader.new(StringIO.new(body)).read
+        rescue Zlib::Error, Zlib::GzipFile::Error
+          # If decompression fails, we'll try to parse the raw body anyway
+        end
+      elsif response['Content-Encoding'] == 'deflate' && body && !body.empty?
+        begin
+          body = Zlib::Inflate.inflate(body)
+        rescue Zlib::Error
+          # If decompression fails, we'll try to parse the raw body anyway
+        end
+      end
+
+      begin
+        parsed = JSON.parse(body)
+      rescue JSON::ParserError
+        raise Error, "Invalid JSON response from Zyte API (#{response.code}): #{body.to_s[0..100]}..."
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        error_msg = parsed['detail'] || parsed['title'] || response.message
+        raise Error, "Zyte API Error (#{response.code}): #{error_msg}"
+      end
+
+      parsed
+    end
+  end
+end

data/lib/zyterb.rb

@@ -0,0 +1,31 @@
+require "zyterb/client"
+
+module Zyterb
+  class Error < StandardError; end
+
+  class Configuration
+    attr_accessor :api_key
+
+    def initialize
+      @api_key = nil
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configuration=(config)
+      @configuration = config
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,43 @@
+--- !ruby/object:Gem::Specification
+name: zyterb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zyterb Author
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Simple Ruby client to extract data and take screenshots using Zyte API.
+email:
+- author@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/zyterb.rb
+- lib/zyterb/client.rb
+homepage: https://github.com/getletterpress/zyterb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: A zero-dependency Ruby client for the Zyte API
+test_files: []