serqo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7dc2911cd34ade0dc1143e6df69d3cb81385d3f487e438387900a3d9334bd556
+  data.tar.gz: e308b2916891f8ba3fbedd8e6b6ef4ca7862a7f68a08a952c848ab184a4487ac
+SHA512:
+  metadata.gz: 875852674ccf27cf1f02e065b3d0025223e666cef2884c0e1dabd3a61f1cfa3a30b725e80a595ebd730a09d8129d04a2cc5df5a9f995ba9ffffd4f92c88d15bc
+  data.tar.gz: 21a68d0d8289d4cd83ac22dc8e55b8a163b4e08579572aac91aa9f4ec6dfd24affd0f8d00128d87254512c05b385d0c90a390da85bb0d949ec0860b6501046cc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serqo
+
+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,37 @@
+# Serqo Ruby SDK
+
+Official Ruby client for the Serqo Search API. Requires Ruby 3.1 or later and uses the standard library.
+
+## Install
+
+```sh
+gem install serqo
+```
+
+## Quick start
+
+```ruby
+require "serqo"
+
+client = Serqo::Client.new(api_key: ENV.fetch("SERQO_API_KEY"))
+response = client.search({
+  "q" => "espresso machines",
+  "engine" => "google",
+  "type" => "web",
+  "gl" => "us",
+  "hl" => "en"
+})
+
+puts response.dig("data", "results")
+puts "Request ID: #{response.fetch('requestId')}"
+```
+
+Keep the API key in server-side configuration. Methods return the full response envelope as hashes.
+
+## Methods and errors
+
+- `search(query, idempotency_key: nil)` sends `POST /v1/search`.
+- `engines`, `me`, and `health` call the corresponding endpoints.
+- API failures raise `Serqo::Error` with `status`, `code`, `request_id`, `retryable`, `retry_after_ms`, and `details`.
+- The client never retries searches automatically. Reuse an idempotency key only with identical parameters.
+- See the [shared API reference](API.md) for all search parameters, response fields, and pagination behavior.

data/lib/serqo.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Serqo
+  # Structured API error. Inspect status, code, request_id, and retryable.
+  class Error < StandardError
+    attr_reader :status, :code, :request_id, :retryable, :retry_after_ms, :details
+
+    def initialize(status:, body: {}, request_id: nil)
+      @status = status
+      @code = body["code"] || "UNKNOWN_ERROR"
+      @request_id = request_id
+      @retryable = body.fetch("retryable", false)
+      @retry_after_ms = body["retryAfterMs"]
+      @details = body["details"]
+      super(body["message"] || "Serqo API request failed with HTTP #{status}")
+    end
+  end
+
+  # Small standard-library client for the public Serqo Search API.
+  class Client
+    DEFAULT_BASE_URL = "https://api.serqo.io"
+
+    # @param api_key [String] Secret key; keep it in trusted server config.
+    # @param base_url [String] API origin without a trailing slash.
+    # @param timeout [Integer] Read timeout in seconds (default 60).
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 60)
+      raise ArgumentError, "api_key is required" if api_key.strip.empty?
+
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+    end
+
+    # Run one search. Pass an idempotency key only when retrying the same query.
+    def search(query, idempotency_key: nil)
+      headers = {}
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+      request("POST", "/v1/search", body: query, headers: headers)
+    end
+
+    # Return the current engine and search-type capability list.
+    def engines
+      request("GET", "/v1/engines")
+    end
+
+    # Return account and key identifiers associated with this API key.
+    def me
+      request("GET", "/v1/me")
+    end
+
+    # Check the product API process without sending an API key.
+    def health
+      request("GET", "/v1/health", authenticated: false)
+    end
+
+    private
+
+    def request(method, path, body: nil, headers: {}, authenticated: true)
+      uri = URI("#{@base_url}#{path}")
+      request_class = method == "POST" ? Net::HTTP::Post : Net::HTTP::Get
+      http_request = request_class.new(uri)
+      http_request["Accept"] = "application/json"
+      http_request["x-api-key"] = @api_key if authenticated
+      headers.each { |name, value| http_request[name] = value }
+      http_request.body = JSON.generate(body) if body
+      http_request["Content-Type"] = "application/json" if body
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: @timeout) do |http|
+        http.request(http_request)
+      end
+      payload = JSON.parse(response.body)
+      unless response.is_a?(Net::HTTPSuccess)
+        error_body = payload.is_a?(Hash) ? (payload["error"] || {}) : {}
+        request_id = payload.is_a?(Hash) ? payload["requestId"] : nil
+        raise Error.new(status: response.code.to_i, body: error_body, request_id: request_id || response["x-request-id"])
+      end
+      raise Error.new(status: response.code.to_i, body: { "code" => "INVALID_RESPONSE" }) unless payload.is_a?(Hash) && payload["success"] == true
+
+      payload
+    end
+  end
+end

metadata

@@ -0,0 +1,42 @@
+--- !ruby/object:Gem::Specification
+name: serqo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Serqo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A dependency-free HTTP client for the public Serqo Search API.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/serqo.rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://serqo.io
+  source_code_uri: https://github.com/serqo-io/serqo-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the Serqo Search API
+test_files: []