Class: Synoppy::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/synoppy.rb

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 60) ⇒ Client

Returns a new instance of Client.

Raises:

  • (ArgumentError) 


24
25
26
27
28
29
30
 
# File 'lib/synoppy.rb', line 24

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

Instance Method Details

#act ⇒ Object

Take actions on a page (click, type, navigate). Coming soon —/api/act is not live yet.

Raises:

  • (NotImplementedError) 


176
177
178
 
# File 'lib/synoppy.rb', line 176

def act(*)
  raise NotImplementedError, "act is coming soon — /api/act is not live yet"
end

#classify(url, labels: nil) ⇒ Object

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.



118
119
120
121
122
 
# File 'lib/synoppy.rb', line 118

def classify(url, labels: nil)
  body = { url: url }
  body[:labels] = labels unless labels.nil?
  request("/api/classify", body)
end

#crawl(url, limit: nil) ⇒ Object

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 }.



77
78
79
80
81
 
# File 'lib/synoppy.rb', line 77

def crawl(url, limit: nil)
  body = { url: url }
  body[:limit] = limit unless limit.nil?
  request("/api/crawl", body)
end

#enrich(url = nil, domain: nil, email: nil) ⇒ Object Also known as: brand

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 }.



130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/synoppy.rb', line 130

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

#extract(url, prompt: nil, instruction: nil, schema: nil) ⇒ Object

AI-structured JSON extraction (requires a key).

prompt: natural-language instruction describing the JSON to return.

`instruction:` is accepted as an alias for `prompt:`.

schema: optional JSON Schema (a Hash) to constrain the output shape.

When provided, `data` conforms to it.

Returns { success, url, model, data, metadata, truncated, usage:{ inputTokens, outputTokens }, latencyMs, creditsUsed, creditsRemaining }.



101
102
103
104
105
106
107
 
# File 'lib/synoppy.rb', line 101

def extract(url, prompt: nil, instruction: nil, schema: nil)
  body = { url: url }
  prompt ||= instruction
  body[:prompt] = prompt unless prompt.nil?
  body[:schema] = schema unless schema.nil?
  request("/api/extract", body)
end

#images(url) ⇒ Object

Pull every image off a page.

Returns { success, url, count, images:[{ src, alt, width, height }], bytesIn, latencyMs, creditsUsed, creditsRemaining }.



148
149
150
 
# File 'lib/synoppy.rb', line 148

def images(url)
  request("/api/images", { url: url })
end

#map(url) ⇒ Object Also known as: sitemap

Discover every URL on a domain.

Returns { success, domain, urls: string[], count, source: “sitemap” | “links”, latencyMs, creditsUsed, creditsRemaining }.



87
88
89
 
# File 'lib/synoppy.rb', line 87

def map(url)
  request("/api/map", { url: url })
end

#read(url, formats: nil, only_main_content: nil, timeout_ms: nil, render: nil, wait_ms: nil) ⇒ Object Also known as: scrape

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 }.



43
44
45
46
47
48
49
50
51
 
# File 'lib/synoppy.rb', line 43

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

#screenshot(url, full_page: nil, wait_ms: nil, timeout_ms: nil) ⇒ Object

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.



62
63
64
65
66
67
68
 
# File 'lib/synoppy.rb', line 62

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

#search(query, max_results: nil, markdown: nil, include_domains: nil, exclude_domains: nil, fanout: nil) ⇒ Object

Web search -> clean, ranked results (requires a key).

query : the search query (required). max_results : number of results to return (1-15). markdown : also read each result to clean markdown, in one trip (boolean). include_domains: only return results from these domains (array of strings). exclude_domains: never return results from these domains (array of strings). fanout : expand the query into variations for higher recall (boolean,

costs more).

Returns { success, query, results:[{ title, url, snippet, markdown? }], latencyMs, creditsUsed, creditsRemaining }.



164
165
166
167
168
169
170
171
172
 
# File 'lib/synoppy.rb', line 164

def search(query, max_results: nil, markdown: nil, include_domains: nil, exclude_domains: nil, fanout: nil)
  body = { query: query }
  body[:maxResults] = max_results unless max_results.nil?
  body[:markdown] = markdown unless markdown.nil?
  body[:includeDomains] = include_domains unless include_domains.nil?
  body[:excludeDomains] = exclude_domains unless exclude_domains.nil?
  body[:fanout] = fanout unless fanout.nil?
  request("/api/search", body)
end