scavio 0.24.1 → 0.26.0

package/README.md

@@ -1,13 +1,14 @@
 # Scavio
 
 TypeScript SDK for the [Scavio API](https://scavio.dev?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) — real-time structured web
-data across 36 platforms on one API key, plus `extract()` to read
+data across 38 platforms on one API key, plus `extract()` to read
 any URL as clean Markdown, and `extract.map()` / `extract.crawl()` /
 `extract.batch()` to map, crawl and batch-extract whole websites.
 
 Structured JSON in, structured JSON out. No per-site parsers to maintain.
 
 - **Search and SERP** — Google (organic, news, maps, shopping, flights, hotels, trends, AI Mode)
+- **AI assistants** — ChatGPT and Gemini answers with the sources they cite and the products they recommend
 - **E-commerce** — Amazon, Walmart, Costco, Mercado Libre, eBay, Target, Home Depot, TikTok Shop
 - **Real estate and travel** — Zillow, Redfin, Realtor.com, Rightmove, Booking, Airbnb, Tripadvisor
 - **Reviews and local** — Trustpilot, Yelp, G2, Capterra, Glassdoor, App Store, Google Play
@@ -261,6 +262,63 @@ await client.google.news({ query: "openai" });
 await client.google.trends({ query: "bitcoin" });
 ```
 
+#### Migrating from the Google Custom Search JSON API (new in 0.25.0)
+
+`google.customSearch` takes the Custom Search JSON API (`cse.list`) parameters and
+returns the same `customsearch#search` response: `items[]` with `title`, `link`,
+`snippet` and `displayLink`, `searchInformation.totalResults` and
+`queries.nextPage`, so code that parsed Custom Search results keeps working.
+Options are snake_case like the rest of this SDK and are sent as the CSE wire
+names (`site_search` -> `siteSearch`, `date_restrict` -> `dateRestrict`). 1 credit.
+
+```typescript
+const res = await client.google.customSearch({
+  q: "abortcontroller fetch timeout",
+  num: 5,
+  site_search: "stackoverflow.com", // enforced on the returned results
+  date_restrict: "y1",
+});
+for (const item of res.items ?? []) console.log(item.displayLink, item.title, item.link);
+const next = res.queries.nextPage?.[0]?.startIndex;
+```
+
+Not using this SDK? Keep your existing Custom Search code and change the host:
+`https://api.scavio.dev/customsearch/v1?key=YOUR_SCAVIO_KEY&q=...`. `cx` is
+accepted and ignored. Parameters that cannot be honoured (image search, `sort`,
+`rights`) throw `BadRequestError` instead of being silently dropped. For the full
+SERP (knowledge graph, AI overview, People Also Ask) use `google.search`.
+[Docs](https://scavio.dev/docs/google-custom-search-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme)
+
+### ChatGPT and Gemini (new in 0.26.0)
+
+Send the prompt a buyer would ask and get the answer the assistant gives: the
+full Markdown answer, the pages it cites, the web searches it ran (ChatGPT) and
+the products it recommended. Both return the same shape under `data`, so one
+parser tracks which brands each assistant recommends. 5 credits per answered
+prompt; a failed prompt is not charged. Answers take 10-40 seconds, so both
+methods raise the request timeout to 120s when the client's is shorter.
+
+```typescript
+const prompt = "What are the best CRM tools for small agencies?";
+
+const chatgpt = await client.chatgpt.prompt({ prompt, country: "us" });
+const gemini = await client.gemini.prompt({ prompt });
+
+for (const { data } of [chatgpt, gemini] as any[]) {
+  console.log(data.platform, "mentions HubSpot:", data.answer.markdown.includes("HubSpot"));
+  console.log("  cited:", data.sources.slice(0, 5).map((s: any) => s.url));
+  console.log("  products:", data.shopping.map((p: any) => p.title));
+}
+
+// ChatGPT also returns each source's title and publisher and the searches it ran.
+console.log((chatgpt as any).data.search_queries);
+```
+
+Options: `chatgpt.prompt({ prompt, model?, country?, include_html? })` (prompt up
+to 1024 characters) and `gemini.prompt({ prompt })` (up to 4000).
+[ChatGPT docs](https://scavio.dev/docs/chatgpt-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme) |
+[Gemini docs](https://scavio.dev/docs/gemini-api?utm_source=npm-scavio-js&utm_medium=package&utm_campaign=readme)
+
 ### Amazon
 
 Responses are normalized to a stable shape (see the breaking-change note

package/dist/index.cjs

@@ -30,18 +30,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AI_PROMPT_TIMEOUT: () => AI_PROMPT_TIMEOUT,
   AirbnbNamespace: () => AirbnbNamespace,
   AmazonNamespace: () => AmazonNamespace,
   AppStoreNamespace: () => AppStoreNamespace,
   BadRequestError: () => BadRequestError,
   BookingNamespace: () => BookingNamespace,
   CapterraNamespace: () => CapterraNamespace,
+  ChatgptNamespace: () => ChatgptNamespace,
   CompaniesHouseNamespace: () => CompaniesHouseNamespace,
   CostcoNamespace: () => CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND: () => DEFAULT_MAX_REQUESTS_PER_SECOND,
   EbayNamespace: () => EbayNamespace,
   ExtractNamespace: () => ExtractNamespace,
   G2Namespace: () => G2Namespace,
+  GeminiNamespace: () => GeminiNamespace,
   GlassdoorNamespace: () => GlassdoorNamespace,
   GoogleAdsNamespace: () => GoogleAdsNamespace,
   GoogleNamespace: () => GoogleNamespace,
@@ -232,7 +235,7 @@ function parseRetryAfter(header) {
 var BASE_URL = "https://api.scavio.dev";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = true ? "0.24.1" : "0.0.0";
+var SDK_VERSION = true ? "0.26.0" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -421,6 +424,15 @@ var AmazonNamespace = class {
 };
 
 // src/namespaces/google.ts
+var CUSTOM_SEARCH_WIRE = {
+  date_restrict: "dateRestrict",
+  site_search: "siteSearch",
+  site_search_filter: "siteSearchFilter",
+  exact_terms: "exactTerms",
+  exclude_terms: "excludeTerms",
+  or_terms: "orTerms",
+  file_type: "fileType"
+};
 var GoogleNamespace = class {
   constructor(client) {
     this.client = client;
@@ -430,6 +442,21 @@ var GoogleNamespace = class {
   async search(options) {
     return this.client._post("/api/v2/google", options);
   }
+  /**
+   * Google search in the Custom Search JSON API format: a drop-in for cse.list.
+   * Returns customsearch#search (items[], searchInformation, queries.nextPage)
+   * plus a scavio billing object, so CSE parsing code keeps working. For the
+   * full SERP (knowledge graph, AI overview, People Also Ask) use search().
+   * Unsupported CSE params (image search, sort, rights) throw BadRequestError.
+   * 1 credit.
+   */
+  async customSearch(options) {
+    const body = {};
+    for (const [key, value] of Object.entries(options)) {
+      body[CUSTOM_SEARCH_WIRE[key] ?? key] = value;
+    }
+    return await this.client._post("/api/v1/google/customsearch", body);
+  }
   /** Google AI Mode answer. */
   async aiMode(options) {
     return this.client._post("/api/v2/google/ai-mode", options);
@@ -2792,6 +2819,43 @@ var TrustpilotNamespace = class {
   }
 };
 
+// src/namespaces/chatgpt.ts
+var AI_PROMPT_TIMEOUT = 12e4;
+var ChatgptNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Send a prompt to ChatGPT and get the answer it gives: the full Markdown
+   * answer, every page it cites (title, publisher, date), the web searches it
+   * ran and the products it recommended. Built for AI visibility monitoring.
+   *
+   * Costs 5 credits per answered prompt; failed prompts are not charged.
+   */
+  async prompt(options) {
+    return this.client._post("/api/v1/chatgpt/prompt", options, void 0, AI_PROMPT_TIMEOUT);
+  }
+};
+
+// src/namespaces/gemini.ts
+var GeminiNamespace = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Send a prompt to Google Gemini and get the answer it gives as Markdown,
+   * with the URLs it cites and the products it recommended. Same response
+   * shape as chatgpt.prompt().
+   *
+   * Costs 5 credits per answered prompt; failed prompts are not charged.
+   */
+  async prompt(options) {
+    return this.client._post("/api/v1/gemini/prompt", options, void 0, AI_PROMPT_TIMEOUT);
+  }
+};
+
 // src/namespaces/realtor.ts
 var RealtorNamespace = class {
   constructor(client) {
@@ -3194,6 +3258,8 @@ var Scavio = class extends ScavioCore {
   metaAds;
   costco;
   trustpilot;
+  chatgpt;
+  gemini;
   realtor;
   rightmove;
   mercadolibre;
@@ -3251,6 +3317,8 @@ var Scavio = class extends ScavioCore {
     this.metaAds = new MetaAdsNamespace(this);
     this.costco = new CostcoNamespace(this);
     this.trustpilot = new TrustpilotNamespace(this);
+    this.chatgpt = new ChatgptNamespace(this);
+    this.gemini = new GeminiNamespace(this);
     this.realtor = new RealtorNamespace(this);
     this.rightmove = new RightmoveNamespace(this);
     this.mercadolibre = new MercadoLibreNamespace(this);
@@ -3266,13 +3334,13 @@ var Scavio = class extends ScavioCore {
     });
   }
   /** @internal */
-  async _post(path, body, headers) {
+  async _post(path, body, headers, minTimeout) {
     return request({
       method: "POST",
       path,
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
-      timeout: this.timeout,
+      timeout: Math.max(this.timeout, minTimeout ?? 0),
       maxRetries: this.maxRetries,
       rateLimiter: this.rateLimiter,
       body,
@@ -3357,18 +3425,21 @@ async function getSubtle() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AI_PROMPT_TIMEOUT,
   AirbnbNamespace,
   AmazonNamespace,
   AppStoreNamespace,
   BadRequestError,
   BookingNamespace,
   CapterraNamespace,
+  ChatgptNamespace,
   CompaniesHouseNamespace,
   CostcoNamespace,
   DEFAULT_MAX_REQUESTS_PER_SECOND,
   EbayNamespace,
   ExtractNamespace,
   G2Namespace,
+  GeminiNamespace,
   GlassdoorNamespace,
   GoogleAdsNamespace,
   GoogleNamespace,