serpcheap-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b835b2a8d37f97ccae48b83a9a749a0b3f1a02dabbe4884a2d3c039ae24682cf
+  data.tar.gz: 98a3fc890644c89df7d3a3ba3b2ace65911162504adb68a6d322ee8ecd29276f
+SHA512:
+  metadata.gz: fafabef66a5cd3146bdcedced78199d19224be680b9912b667087c1ca71a7acf1f7d56a614b2619b71ed7d509095bfe4259e8559297b51bc1e6f1a9183e8130c
+  data.tar.gz: 4a7b84a516a5805486737c9fb9e98d3c2b29ed7be1fbe1065ec56b1b7d75cb82296c3ed50c6ed0c9204ec988f30876778dce113da58e133c262404d21e9635b3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) serp.cheap
+
+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,68 @@
+# serpcheap-rails
+
+Rails integration for the [serp.cheap](https://serp.cheap) **Google Search API** — real-time Google SERP data (organic results, ads, knowledge graph, page scraping, rank tracking) wrapped with a Railtie, `Rails.cache` result caching, credentials/ENV config, and an ActiveJob.
+
+It's the **cheapest Google Search API** we know of — $0.0003 per cached search, $0.0006 fresh, no monthly minimum (~10× cheaper than SerpApi).
+
+## Install
+
+```ruby
+# Gemfile
+gem "serpcheap-rails"
+```
+
+Set your API key (get one at [app.serp.cheap](https://app.serp.cheap)) via `SERPCHEAP_API_KEY`, Rails credentials, or an initializer:
+
+```ruby
+# config/initializers/serpcheap.rb
+SerpCheap::Rails.configure do |c|
+  c.api_key = Rails.application.credentials.serpcheap_api_key
+  # c.cache_ttl = 3600
+  # c.cache_enabled = true
+end
+```
+
+You can also configure it the Rails way in any environment file:
+
+```ruby
+config.serpcheap.api_key = ENV["SERPCHEAP_API_KEY"]
+config.serpcheap.cache_ttl = 1.hour
+```
+
+## Usage
+
+```ruby
+results = SerpCheap::Rails.search("best running shoes", gl: "us")
+page    = SerpCheap::Rails.scrape("https://example.com")
+rank    = SerpCheap::Rails.rank("example.com", "best running shoes")
+```
+
+Results are cached in `Rails.cache` by default (keyed by query + options) so repeat calls don't spend credits. Reach the raw, uncached SDK client when you need it:
+
+```ruby
+SerpCheap::Rails.raw.search_pages("best running shoes", from: 1, to: 3)
+```
+
+### Background cache warming
+
+Pre-warm the cache off the request cycle with the bundled ActiveJob:
+
+```ruby
+SerpCheap::Rails::SearchJob.perform_later("best running shoes", "gl" => "br")
+```
+
+## Configuration
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `api_key` | `ENV["SERPCHEAP_API_KEY"]` | API key (required) |
+| `base_url` | `https://api.serp.cheap` | API base URL |
+| `timeout_ms` | `15000` | Per-request timeout |
+| `max_retries` | `2` | Retry count on transient errors |
+| `cache_enabled` | `true` | Toggle `Rails.cache` result caching |
+| `cache_store` | `Rails.cache` | Any `ActiveSupport::Cache::Store` |
+| `cache_ttl` | `3600` | Cache TTL in seconds |
+
+## License
+
+MIT

data/lib/serpcheap/rails/cached_client.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module SerpCheap
+  module Rails
+    class CachedClient
+      def initialize(sdk, configuration)
+        @sdk = sdk
+        @configuration = configuration
+      end
+
+      def raw
+        @sdk
+      end
+
+      def search(query, **opts)
+        fetch("search", [query, opts]) { @sdk.search(query, **opts) }
+      end
+
+      def scrape(url, **opts)
+        fetch("scrape", [url, opts]) { @sdk.scrape(url, **opts) }
+      end
+
+      def rank(url, query, **opts)
+        fetch("rank", [url, query, opts]) { @sdk.rank(url, query, **opts) }
+      end
+
+      private
+
+      def fetch(kind, key_parts)
+        store = @configuration.cache_store
+        return yield unless @configuration.cache_enabled && store
+
+        key = "serpcheap:#{kind}:#{Digest::MD5.hexdigest(JSON.generate(normalize(key_parts)))}"
+        store.fetch(key, expires_in: @configuration.cache_ttl) { yield }
+      end
+
+      def normalize(value)
+        case value
+        when Hash then value.sort_by { |k, _| k.to_s }.to_h.transform_values { |v| normalize(v) }
+        when Array then value.map { |v| normalize(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/serpcheap/rails/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SerpCheap
+  module Rails
+    class Configuration
+      attr_accessor :api_key, :base_url, :timeout_ms, :max_retries,
+                    :cache_enabled, :cache_ttl, :cache_store
+
+      def initialize
+        @api_key = ENV.fetch("SERPCHEAP_API_KEY", nil)
+        @base_url = ENV.fetch("SERPCHEAP_BASE_URL", nil)
+        @timeout_ms = 15_000
+        @max_retries = 2
+        @cache_enabled = true
+        @cache_ttl = 3600
+        @cache_store = nil
+      end
+    end
+  end
+end

data/lib/serpcheap/rails/railtie.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "active_support/ordered_options"
+
+module SerpCheap
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.serpcheap = ActiveSupport::OrderedOptions.new
+
+      initializer "serpcheap.configure" do |app|
+        SerpCheap::Rails.apply_options(app.config.serpcheap)
+      end
+
+      config.after_initialize do
+        SerpCheap::Rails.configuration.cache_store ||= ::Rails.cache
+      end
+    end
+  end
+end

data/lib/serpcheap/rails/search_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module SerpCheap
+  module Rails
+    # Warms the result cache off the request cycle:
+    #   SerpCheap::Rails::SearchJob.perform_later("best running shoes", "gl" => "br")
+    class SearchJob < ActiveJob::Base
+      def perform(query, opts = {})
+        SerpCheap::Rails.search(query, **symbolize(opts))
+      end
+
+      private
+
+      def symbolize(opts)
+        opts.each_with_object({}) { |(k, v), out| out[k.to_sym] = v }
+      end
+    end
+  end
+end

data/lib/serpcheap/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SerpCheap
+  module Rails
+    VERSION = "0.1.0" # x-release-please-version
+  end
+end

data/lib/serpcheap/rails.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "serpcheap"
+
+require_relative "rails/version"
+require_relative "rails/configuration"
+require_relative "rails/cached_client"
+
+module SerpCheap
+  # Rails integration: a Railtie wires config + Rails.cache; SerpCheap::Rails
+  # exposes a cached search/scrape/rank facade and a raw client escape hatch.
+  module Rails
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration) if block_given?
+        reset_client!
+        configuration
+      end
+
+      def apply_options(options)
+        c = configuration
+        c.api_key = options[:api_key] unless options[:api_key].nil?
+        c.base_url = options[:base_url] unless options[:base_url].nil?
+        c.timeout_ms = options[:timeout_ms] unless options[:timeout_ms].nil?
+        c.max_retries = options[:max_retries] unless options[:max_retries].nil?
+        c.cache_store = options[:cache_store] unless options[:cache_store].nil?
+        c.cache_enabled = options[:cache_enabled] unless options[:cache_enabled].nil?
+        c.cache_ttl = options[:cache_ttl] unless options[:cache_ttl].nil?
+        reset_client!
+        c
+      end
+
+      def reset_client!
+        @client = nil
+      end
+
+      def client
+        @client ||= build_client
+      end
+
+      def raw
+        client.raw
+      end
+
+      def search(query, **opts)
+        client.search(query, **opts)
+      end
+
+      def scrape(url, **opts)
+        client.scrape(url, **opts)
+      end
+
+      def rank(url, query, **opts)
+        client.rank(url, query, **opts)
+      end
+
+      private
+
+      def build_client
+        c = configuration
+        if c.api_key.nil? || c.api_key.empty?
+          raise SerpCheap::Error.new(
+            "missing_api_key",
+            "Set SerpCheap::Rails api_key (or SERPCHEAP_API_KEY). Get a key at https://app.serp.cheap."
+          )
+        end
+        sdk = SerpCheap::Client.new(
+          c.api_key,
+          base_url: c.base_url,
+          timeout_ms: c.timeout_ms,
+          max_retries: c.max_retries
+        )
+        CachedClient.new(sdk, c)
+      end
+    end
+  end
+end
+
+require_relative "rails/railtie"
+require_relative "rails/search_job"

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: serpcheap-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- serp.cheap
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: serpcheap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Railtie, cached client (Rails.cache), credentials/ENV config, and an
+  ActiveJob for the serp.cheap SERP API.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/serpcheap/rails.rb
+- lib/serpcheap/rails/cached_client.rb
+- lib/serpcheap/rails/configuration.rb
+- lib/serpcheap/rails/railtie.rb
+- lib/serpcheap/rails/search_job.rb
+- lib/serpcheap/rails/version.rb
+homepage: https://serp.cheap
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://serp.cheap
+  source_code_uri: https://github.com/SerpCheap/serpcheap-rails
+  documentation_uri: https://serp.cheap/docs
+  rubygems_mfa_required: 'true'
+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.16
+signing_key:
+specification_version: 4
+summary: Rails integration for the serp.cheap Google Search API.
+test_files: []