synoppy 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65693e5a2c5e7bef8b207227c4d606efb03adeff7780cee0963d145b5eeebb32
+  data.tar.gz: a4e650761ee1432f0c49e3dd9de39bcbf469c224ee28b792891f1e8d16a735bc
+SHA512:
+  metadata.gz: 34f4c23fdd06970a58d5d57c7b78409bacc1e29050edfb2fe1de44c84fd9e6cb6e18b0b335d91a3a51e803182de6a7b8427f231b5eeff864828ed5b2ff2b304e
+  data.tar.gz: 2966d35ea34895a70f7079d2e1a1480de70cbbc603113846b786f05cd49208969f52eec971cc27c770169841c8a40226be5edc1e95ee1533b2bf04d0d7591f01

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saanora
+
+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,190 @@
+# synoppy (Ruby)
+
+[![Gem](https://img.shields.io/gem/v/synoppy.svg)](https://rubygems.org/gems/synoppy)
+
+**Give your AI agents the whole web.** Synoppy is the web-data layer for AI agents — one key to **read, crawl, map, extract, classify & enrich** any site, plus screenshots and image scraping. Pure `net/http`, zero runtime dependencies.
+
+[**Get a free key →**](https://synoppy.com/dashboard) · [Docs](https://synoppy.com/docs) · [synoppy.com](https://synoppy.com)
+
+```bash
+gem install synoppy
+```
+
+## Quickstart
+
+```ruby
+require "synoppy"
+
+client = Synoppy::Client.new(api_key: ENV["SYNOPPY_API_KEY"])
+
+# Read any URL -> clean markdown
+page = client.read("https://stripe.com/blog", formats: ["markdown"])
+puts page["markdown"]
+
+# Crawl a site
+site = client.crawl("https://example.com", limit: 25)
+puts "#{site["count"]} of #{site["discovered"]} pages"
+
+# AI structured extraction
+result = client.extract("https://news.ycombinator.com", prompt: "Return { title, summary, topics }")
+p result["data"]
+
+# Brand intelligence
+brand = client.enrich("linear.app")
+p brand["colors"], brand["fonts"], brand["socials"]
+```
+
+`Client.new` also accepts `base_url:` (defaults to `https://synoppy.com`) and `timeout:` (seconds).
+
+## Methods
+
+### `read(url, formats:, only_main_content:, timeout_ms:, render:, wait_ms:)` — alias `scrape`
+
+`POST /api/scrape`. Read a URL into clean `markdown` / `html` / `text`.
+
+```ruby
+page = client.read(
+  "https://stripe.com/blog",
+  formats: ["markdown", "html"],   # "markdown" | "html" | "text"
+  only_main_content: true,         # strip nav/boilerplate
+  timeout_ms: 15_000,              # per-request fetch budget
+  render: "auto",                  # true | false | "auto" — headless browser
+  wait_ms: 500                     # extra wait after load before capture
+)
+page["markdown"]
+page["metadata"]["title"]          # title, description, language, siteName, author,
+                                   # ogImage, sourceUrl, statusCode, wordCount,
+                                   # fetchedAt, rendered, bytesIn
+page["renderMs"]                   # present when rendered
+page["latencyMs"]
+```
+
+### `screenshot(url, full_page:, wait_ms:, timeout_ms:)`
+
+`POST /api/screenshot`. Capture a PNG screenshot, returned as a data URL.
+
+```ruby
+shot = client.screenshot("https://stripe.com", full_page: true, wait_ms: 500)
+shot["screenshot"]   # "data:image/png;base64,..."
+shot["sourceUrl"]
+shot["statusCode"]
+shot["fullPage"]
+```
+
+May raise `Synoppy::Error` with code `RENDER_UNAVAILABLE` (HTTP 503) when the render backend is down.
+
+### `crawl(url, limit:)`
+
+`POST /api/crawl`. Crawl a site into one clean page per discovered URL (requires a key). `limit` is 1–25.
+
+```ruby
+site = client.crawl("https://example.com", limit: 25)
+site["domain"]
+site["discovered"]
+site["count"]
+site["pages"]        # [{ "url", "title", "markdown", "words" }]
+site["credits"]
+```
+
+### `map(url)` — alias `sitemap`
+
+`POST /api/map`. Discover every URL on a domain.
+
+```ruby
+m = client.map("https://example.com")
+m["urls"]            # string[]
+m["count"]
+m["source"]          # "sitemap" | "links"
+m["domain"]
+```
+
+### `extract(url, prompt:)`
+
+`POST /api/extract`. AI-structured JSON extraction (requires a key). `instruction:` is accepted as an alias for `prompt:`.
+
+```ruby
+result = client.extract("https://news.ycombinator.com", prompt: "Return { title, summary, topics }")
+result["data"]
+result["model"]
+result["metadata"]
+result["truncated"]
+result["usage"]      # { "inputTokens", "outputTokens" }
+```
+
+### `classify(url, labels:)`
+
+`POST /api/classify`. Classify a company by industry, or against your own labels (requires a key).
+
+```ruby
+# Default: industry taxonomy
+c = client.classify("https://stripe.com")
+c["data"]["industry"]
+c["data"]["naics_code"]      # also naics_title, naics_sector, naics_sector_title, naics_valid
+c["data"]["sic_code"]        # also sic_title, sic_division, sic_division_title, sic_valid
+c["data"]["categories"]
+c["data"]["confidence"]
+
+# Labels mode
+c = client.classify("https://stripe.com", labels: ["fintech", "ecommerce", "social"])
+c["data"]["label"]
+c["data"]["matched"]
+c["data"]["confidence"]
+c["data"]["reasoning"]
+```
+
+### `enrich(url = nil, domain:, email:)` — alias `brand`
+
+`POST /api/brand`. Resolve a brand into a full profile. Pass exactly one of a positional `url`, `domain:`, or `email:` (a work email is mapped to its domain).
+
+```ruby
+brand = client.enrich("linear.app")
+brand = client.enrich(domain: "linear.app")
+brand = client.enrich(email: "jane@linear.app")
+
+brand["name"]
+brand["description"]
+brand["logo"]
+brand["colors"]      # string[]
+brand["fonts"]       # string[]
+brand["address"]
+brand["socials"]     # [{ "label", "url" }]
+brand["domain"]
+```
+
+### `images(url)`
+
+`POST /api/images`. Pull every image off a page.
+
+```ruby
+imgs = client.images("https://stripe.com")
+imgs["count"]
+imgs["images"]       # [{ "src", "alt", "width", "height" }]
+```
+
+### Coming soon
+
+`act` is not live yet — the method exists but raises `NotImplementedError`. It will map to `/api/act` once that endpoint ships.
+
+## Credits
+
+Every successful response includes `creditsUsed` (number) and `creditsRemaining` (number or `nil`) at the top level, on every method:
+
+```ruby
+page = client.read("https://stripe.com")
+puts "used #{page["creditsUsed"]}, #{page["creditsRemaining"]} remaining"
+
+shot = client.screenshot("https://stripe.com")
+puts "used #{shot["creditsUsed"]}, #{shot["creditsRemaining"]} remaining"
+```
+
+## Errors
+
+```ruby
+begin
+  client.crawl("https://example.com")
+rescue Synoppy::Error => e
+  warn "#{e.code} #{e.status}: #{e.message}"
+end
+```
+
+MIT licensed.

data/lib/synoppy.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+# Official Ruby SDK for the Synoppy web-data API.
+module Synoppy
+  VERSION = "1.0.0"
+  DEFAULT_BASE_URL = "https://synoppy.com"
+
+  # Raised when the API returns an error response.
+  class Error < StandardError
+    attr_reader :code, :status
+
+    def initialize(message, code, status)
+      super(message)
+      @code = code
+      @status = status
+    end
+  end
+
+  class Client
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 60)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+    end
+
+    # Read a URL -> clean markdown / HTML / text.
+    #
+    # formats          : array of "markdown" | "html" | "text"
+    # only_main_content: strip nav/boilerplate (boolean)
+    # timeout_ms       : per-request fetch budget in ms
+    # render           : true | false | "auto" — run a headless browser before scraping
+    # wait_ms          : extra wait after load (ms) before capture
+    #
+    # Returns { success, metadata { title, description, language, siteName, author,
+    # ogImage, sourceUrl, statusCode, wordCount, fetchedAt, rendered, bytesIn },
+    # markdown?, html?, text?, renderMs?, latencyMs, creditsUsed, creditsRemaining }.
+    def read(url, formats: nil, only_main_content: nil, timeout_ms: nil, render: nil, wait_ms: nil)
+      body = { url: url }
+      body[:formats] = formats unless formats.nil?
+      body[:onlyMainContent] = only_main_content unless only_main_content.nil?
+      body[:timeoutMs] = timeout_ms unless timeout_ms.nil?
+      body[:render] = render unless render.nil?
+      body[:waitMs] = wait_ms unless wait_ms.nil?
+      request("/api/scrape", body)
+    end
+    alias scrape read
+
+    # Capture a full PNG screenshot of a URL (returned as a data URL).
+    #
+    # full_page : capture the entire scrollable page (boolean)
+    # wait_ms   : extra wait after load (ms) before capture
+    # timeout_ms: per-request budget in ms
+    #
+    # Returns { success, screenshot (PNG data URL), sourceUrl, statusCode, fullPage,
+    # latencyMs, creditsUsed, creditsRemaining }. May 503 RENDER_UNAVAILABLE.
+    def screenshot(url, full_page: nil, wait_ms: nil, timeout_ms: nil)
+      body = { url: url }
+      body[:fullPage] = full_page unless full_page.nil?
+      body[:waitMs] = wait_ms unless wait_ms.nil?
+      body[:timeoutMs] = timeout_ms unless timeout_ms.nil?
+      request("/api/screenshot", body)
+    end
+
+    # Crawl a site -> one clean page per URL discovered (requires a key).
+    #
+    # limit: number of pages to crawl (1-25).
+    #
+    # Returns { success, domain, discovered, count,
+    # pages:[{ url, title, markdown, words }], credits, latencyMs,
+    # creditsUsed, creditsRemaining }.
+    def crawl(url, limit: nil)
+      body = { url: url }
+      body[:limit] = limit unless limit.nil?
+      request("/api/crawl", body)
+    end
+
+    # Discover every URL on a domain.
+    #
+    # Returns { success, domain, urls: string[], count,
+    # source: "sitemap" | "links", latencyMs, creditsUsed, creditsRemaining }.
+    def map(url)
+      request("/api/map", { url: url })
+    end
+    alias sitemap map
+
+    # AI-structured JSON extraction (requires a key).
+    #
+    # prompt: natural-language instruction describing the JSON to return.
+    #         `instruction:` is accepted as an alias for `prompt:`.
+    #
+    # Returns { success, url, model, data, metadata, truncated,
+    # usage:{ inputTokens, outputTokens }, latencyMs, creditsUsed, creditsRemaining }.
+    def extract(url, prompt: nil, instruction: nil)
+      body = { url: url }
+      prompt ||= instruction
+      body[:prompt] = prompt unless prompt.nil?
+      request("/api/extract", body)
+    end
+
+    # Classify a company by industry or your own labels (requires a key).
+    #
+    # labels: optional array of custom labels. When omitted, returns the default
+    #   industry taxonomy { industry, naics_code, naics_title, naics_sector,
+    #   naics_sector_title, naics_valid, sic_code, sic_title, sic_division,
+    #   sic_division_title, sic_valid, categories, confidence }.
+    #   When provided, returns { label, matched, confidence, reasoning }.
+    #
+    # Plus creditsUsed / creditsRemaining at the top level.
+    def classify(url, labels: nil)
+      body = { url: url }
+      body[:labels] = labels unless labels.nil?
+      request("/api/classify", body)
+    end
+
+    # Resolve a brand into a full profile. Accepts a url:, a domain:, or an
+    # email: (a work email is mapped to its domain). Provide exactly one.
+    #
+    # Returns { success, domain, name, description, logo, colors: string[],
+    # fonts: string[], address, socials:[{ label, url }], bytesIn, latencyMs,
+    # creditsUsed, creditsRemaining }.
+    def enrich(url = nil, domain: nil, email: nil)
+      body = {}
+      body[:url] = url unless url.nil?
+      body[:domain] = domain unless domain.nil?
+      body[:email] = email unless email.nil?
+      if body.empty?
+        raise ArgumentError, "one of url, domain:, or email: is required"
+      end
+
+      request("/api/brand", body)
+    end
+    alias brand enrich
+
+    # Pull every image off a page.
+    #
+    # Returns { success, url, count,
+    # images:[{ src, alt, width, height }], bytesIn, latencyMs,
+    # creditsUsed, creditsRemaining }.
+    def images(url)
+      request("/api/images", { url: url })
+    end
+
+    # Take actions on a page (click, type, navigate). Coming soon —
+    # /api/act is not live yet.
+    def act(*)
+      raise NotImplementedError, "act is coming soon — /api/act is not live yet"
+    end
+
+    private
+
+    def request(path, body)
+      uri = URI("#{@base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @timeout
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Content-Type"] = "application/json"
+      req["User-Agent"] = "synoppy-ruby/#{VERSION}"
+      req.body = JSON.generate(body)
+
+      res = http.request(req)
+      data = begin
+        JSON.parse(res.body)
+      rescue StandardError
+        {}
+      end
+
+      unless res.is_a?(Net::HTTPSuccess) && data["success"] != false
+        raise Error.new(data["error"] || "HTTP #{res.code}", data["code"] || "ERROR", res.code.to_i)
+      end
+
+      data
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: synoppy
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Saanora
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-21 00:00:00.000000000 Z
+dependencies: []
+description: Scrape, screenshot, crawl, map, extract, classify, enrich, and images
+  — one key for the whole web.
+email:
+- support@synoppy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/synoppy.rb
+homepage: https://synoppy.com/docs/sdks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://synoppy.com
+  documentation_uri: https://synoppy.com/docs/sdks
+  source_code_uri: https://github.com/Synoppy/synoppy-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Synoppy web-data API.
+test_files: []