fetchserp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b128502340ba4f1c344156a2216fee1213ae91392acd691acd7ad46c0e42789
+  data.tar.gz: 00b3d29b3419eda1e5a64b08791e78816db3e0ce434db56f8258da6de6b74ca1
+SHA512:
+  metadata.gz: f2d54374bfef6a701cbc120dfee4804fe316bf10f8d98c585b1708401f9072f6bf40e9a58dc9555fbff94dd897f8b2a303d89fbf1338bd227032065e3ea53d9d
+  data.tar.gz: 0f443b9233cf6c120b695d660700ad212ed61a193360d50cdf9adafe9d9fe3016e194997db861254ef84aa12313bb2ef1cb3594a09fbbe7d3391da15946eafe7

data/LICENSE.txt

@@ -0,0 +1,3 @@
+FetchSERP Ruby SDK is licensed under the GNU General Public License v3.0.
+
+See https://www.gnu.org/licenses/gpl-3.0.en.html for the full text. 

data/README.md

@@ -0,0 +1,65 @@
+# FetchSERP Ruby SDK
+
+A lightweight, hand-crafted Ruby SDK for the FetchSERP REST API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "fetchserp", git: "https://github.com/fetchserp/fetchserp-ruby.git"
+```
+
+Then bundle install:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require "fetchserp"
+
+client = FetchSERP::Client.new(api_key: ENV["FETCHSERP_API_KEY"])
+
+# Get backlinks for a domain
+response = client.backlinks(domain: "example.com")
+puts response.data
+
+# Fetch Google SERP results
+serp = client.serp(query: "best ruby gems", country: "us")
+puts serp.data["results"]
+```
+
+The client will raise `FetchSERP::Error` on any HTTP error (network, 4xx, 5xx) so you can handle failures gracefully.
+
+## Supported Endpoints
+
+* `/api/v1/backlinks`
+* `/api/v1/domain_emails`
+* `/api/v1/domain_infos`
+* `/api/v1/keywords_search_volume`
+* `/api/v1/keywords_suggestions`
+* `/api/v1/long_tail_keywords_generator`
+* `/api/v1/page_indexation`
+* `/api/v1/ranking`
+* `/api/v1/scrape`
+* `/api/v1/scrape_domain`
+* `/api/v1/scrape_js`
+* `/api/v1/scrape_js_with_proxy`
+* `/api/v1/serp`
+* `/api/v1/serp_html`
+* `/api/v1/serp_js` & `/api/v1/serp_js/{uuid}`
+* `/api/v1/serp_text`
+* `/api/v1/user`
+* `/api/v1/web_page_ai_analysis`
+* `/api/v1/web_page_seo_analysis`
+
+## Contributing
+
+Bug reports and pull requests are welcome!
+
+## License
+
+GPL-3.0 

data/lib/fetchserp/client.rb

@@ -0,0 +1,187 @@
+require "net/http"
+require "uri"
+require "json"
+require_relative "response"
+
+module FetchSERP
+  # Client is the main entry point for interacting with the FetchSERP API
+  class Client
+    DEFAULT_BASE_URL = "https://www.fetchserp.com".freeze
+
+    # @param api_key [String] Your FetchSERP API key (required)
+    # @param base_url [String] Override the API base url (rarely needed)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30)
+      raise ArgumentError, "api_key is required" if api_key.to_s.strip.empty?
+
+      @api_key  = api_key
+      @base_url = base_url
+      @timeout  = timeout
+    end
+
+    ###########################################################
+    # Public endpoint helpers
+    ###########################################################
+
+    def backlinks(**params)
+      get("/api/v1/backlinks", params)
+    end
+
+    def domain_emails(**params)
+      get("/api/v1/domain_emails", params)
+    end
+
+    def domain_infos(**params)
+      get("/api/v1/domain_infos", params)
+    end
+
+    def keywords_search_volume(**params)
+      get("/api/v1/keywords_search_volume", params)
+    end
+
+    def keywords_suggestions(**params)
+      get("/api/v1/keywords_suggestions", params)
+    end
+
+    def long_tail_keywords_generator(**params)
+      get("/api/v1/long_tail_keywords_generator", params)
+    end
+
+    def page_indexation(**params)
+      get("/api/v1/page_indexation", params)
+    end
+
+    def ranking(**params)
+      get("/api/v1/ranking", params)
+    end
+
+    def scrape(**params)
+      get("/api/v1/scrape", params)
+    end
+
+    def scrape_domain(**params)
+      get("/api/v1/scrape_domain", params)
+    end
+
+    def scrape_js(**params)
+      post("/api/v1/scrape_js", params)
+    end
+
+    def scrape_js_with_proxy(**params)
+      post("/api/v1/scrape_js_with_proxy", params)
+    end
+
+    def serp(**params)
+      get("/api/v1/serp", params)
+    end
+
+    def serp_html(**params)
+      get("/api/v1/serp_html", params)
+    end
+
+    # Step 1: returns uuid
+    def serp_js(**params)
+      get("/api/v1/serp_js", params)
+    end
+
+    # Step 2: pass uuid param (uuid: "...")
+    def serp_js_content(uuid:)
+      raise ArgumentError, "uuid is required" if uuid.to_s.empty?
+      get("/api/v1/serp_js/#{uuid}")
+    end
+
+    def serp_text(**params)
+      get("/api/v1/serp_text", params)
+    end
+
+    def user
+      get("/api/v1/user")
+    end
+
+    def web_page_ai_analysis(**params)
+      get("/api/v1/web_page_ai_analysis", params)
+    end
+
+    def web_page_seo_analysis(**params)
+      get("/api/v1/web_page_seo_analysis", params)
+    end
+
+    ###########################################################
+    # Low-level helpers
+    ###########################################################
+
+    private
+
+    def get(path, params = nil)
+      request(:get, path, params: params)
+    end
+
+    def post(path, params = nil, body: nil)
+      request(:post, path, params: params, body: body)
+    end
+
+    def request(method, path, params: nil, body: nil)
+      uri = URI.join(@base_url, path)
+
+      # merge query params
+      if params&.any?
+        query_hash = params.reject { |_, v| v.nil? }
+        existing = URI.decode_www_form(uri.query || "")
+        new_qs = query_hash.flat_map { |k, v| Array(v).map { |val| [k.to_s, val.to_s] } }
+        uri.query = URI.encode_www_form(existing + new_qs)
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request_class = case method
+                      when :get  then Net::HTTP::Get
+                      when :post then Net::HTTP::Post
+                      else
+                        raise ArgumentError, "Unsupported HTTP method: #{method}"
+                      end
+
+      req = request_class.new(uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body.to_json if body
+
+      response = perform_request_with_redirect(http, req, limit: 5)
+
+      # Raise on HTTP error codes
+      code_int = response.code.to_i
+      if code_int >= 400
+        raise FetchSERP::Error.new("HTTP #{code_int}", status: code_int, body: response.body)
+      end
+
+      Response.new(response)
+    end
+
+    def perform_request_with_redirect(http, req, limit: 5)
+      raise FetchSERP::Error, "Too many redirects" if limit.zero?
+
+      response = http.request(req)
+      case response
+      when Net::HTTPRedirection
+        new_location = response["location"]
+        new_uri = URI.parse(new_location)
+        new_http = Net::HTTP.new(new_uri.host, new_uri.port)
+        new_http.use_ssl = new_uri.scheme == "https"
+        new_req = req.class.new(new_uri)
+        headers.each { |k, v| new_req[k] = v }
+        perform_request_with_redirect(new_http, new_req, limit: limit - 1)
+      else
+        response
+      end
+    end
+
+    def headers
+      {
+        "Authorization" => "Bearer #{@api_key}",
+        "Content-Type" => "application/json",
+        "User-Agent" => "fetchserp-ruby-sdk/#{FetchSERP::VERSION}"
+      }
+    end
+  end
+end 

data/lib/fetchserp/error.rb

@@ -0,0 +1,15 @@
+module FetchSERP
+  # Generic error class for all FetchSERP related exceptions
+  class Error < StandardError
+    attr_reader :status, :body
+
+    # @param message [String]
+    # @param status [Integer, nil] HTTP status code if available
+    # @param body [String, Hash, nil] Raw response body (string or parsed JSON)
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+end 

data/lib/fetchserp/response.rb

@@ -0,0 +1,57 @@
+require "json"
+
+module FetchSERP
+  # Simple wrapper to expose response JSON via `data` and raw HTTP response
+  class Response
+    attr_reader :http_response
+
+    def initialize(http_response)
+      @http_response = http_response
+      @parsed_body = parse_body
+    end
+
+    # Returns parsed JSON body (if JSON) or raw body otherwise
+    # @return [Object]
+    def body
+      @parsed_body
+    end
+
+    # Shortcut accessor for common API structure { "data": ... }
+    def data
+      if @parsed_body.is_a?(Hash) && @parsed_body.key?("data")
+        @parsed_body["data"]
+      else
+        @parsed_body
+      end
+    end
+
+    # Allow convenient hash-like access
+    def [](key)
+      body[key]
+    end
+
+    private
+
+    def parse_body
+      raw_body = @http_response.body
+
+      # If body already parsed (e.g., Hash), return directly.
+      return raw_body unless raw_body.is_a?(String)
+
+      content_type = if @http_response.respond_to?(:headers)
+                       @http_response.headers["content-type"].to_s
+                     else
+                       @http_response["content-type"].to_s
+                     end
+      if content_type.include?("json")
+        begin
+          JSON.parse(raw_body)
+        rescue JSON::ParserError
+          raw_body
+        end
+      else
+        raw_body
+      end
+    end
+  end
+end 

data/lib/fetchserp/version.rb

@@ -0,0 +1,3 @@
+module FetchSERP
+  VERSION = "0.1.0"
+end 

data/lib/fetchserp.rb

@@ -0,0 +1,17 @@
+require_relative "fetchserp/version"
+require_relative "fetchserp/error"
+require_relative "fetchserp/response"
+require_relative "fetchserp/client"
+
+module FetchSERP
+  class << self
+    # Creates a new default client. Convenience wrapper around FetchSERP::Client.new
+    #
+    # @param api_key [String] Your FetchSERP API key
+    # @param kwargs [Hash] Forwarded to Client.initialize
+    # @return [FetchSERP::Client]
+    def new(api_key:, **kwargs)
+      Client.new(api_key: api_key, **kwargs)
+    end
+  end
+end 

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: fetchserp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- FetchSERP
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-19 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight Ruby client for interacting with the FetchSERP API. Provides
+  helpers for authentication and convenient Ruby methods for each endpoint.
+email:
+- contact@fetchserp.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/fetchserp.rb
+- lib/fetchserp/client.rb
+- lib/fetchserp/error.rb
+- lib/fetchserp/response.rb
+- lib/fetchserp/version.rb
+homepage: https://fetchserp.com
+licenses:
+- GPL-3.0-or-later
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the FetchSERP REST API
+test_files: []