scavio 0.24.0 → 0.25.0

package/README.md

@@ -261,6 +261,33 @@ 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)
+
 ### Amazon
 
 Responses are normalized to a stable shape (see the breaking-change note

package/dist/index.cjs

@@ -232,7 +232,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.0" : "0.0.0";
+var SDK_VERSION = true ? "0.25.0" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -421,6 +421,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 +439,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);
@@ -1192,14 +1216,14 @@ var LinkedInNamespace = class {
     return this.client._post("/api/v1/linkedin/post/comments", options);
   }
   /**
-   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * @deprecated Retired. Always returns HTTP 410 and is
    * never billed.
    */
   async personContact(options) {
     return this.client._post("/api/v1/linkedin/person/contact", options);
   }
   /**
-   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * @deprecated Retired. Always returns HTTP 410 and is
    * never billed. `company()` returns `featured_employees`, a small sample of
    * staff profiles.
    */
@@ -1207,21 +1231,21 @@ var LinkedInNamespace = class {
     return this.client._post("/api/v1/linkedin/company/people", options);
   }
   /**
-   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * @deprecated Retired. Always returns HTTP 410 and is
    * never billed. Use `searchJobs()` with the company name as the search term.
    */
   async companyJobs(options) {
     return this.client._post("/api/v1/linkedin/company/jobs", options);
   }
   /**
-   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * @deprecated Retired. Always returns HTTP 410 and is
    * never billed.
    */
   async searchPeople(options) {
     return this.client._post("/api/v1/linkedin/search/people", options);
   }
   /**
-   * @deprecated Retired by the upstream provider. Always returns HTTP 410 and is
+   * @deprecated Retired. Always returns HTTP 410 and is
    * never billed.
    */
   async searchPosts(options) {
@@ -1481,7 +1505,7 @@ var TargetNamespace = class {
    * Paged with `page` + `count` (1-28, default 24). `seller_id` and
    * `seller_name` are null on first-party rows, which means "sold by Target".
    *
-   * Costs 1 credit. Typically ~9s - it runs through a headless browser.
+   * Costs 1 credit. Typically ~9s.
    */
   async search(options) {
     return this.client._post("/api/v1/target/search", options);
@@ -1647,9 +1671,8 @@ var RedfinNamespace = class {
    * houses, schools, climate risk, walkability and location scores, sun
    * exposure, monthly weather, permits, zoning, comparable sales and photos.
    *
-   * Reads the property PAGE, whose inlined request cache replaces the ~40
-   * upstream calls that page made - which is why it is the same price as
-   * search().
+   * Returns the whole property page in one call, which is why it is the same
+   * price as search().
    *
    * Costs 1 credit. Single response, no pagination.
    */
@@ -1879,7 +1902,7 @@ var YelpNamespace = class {
    * count.
    *
    * `term` + `location` or `url` is required, and `location` is effectively
-   * mandatory - Yelp geolocates a location-less search off the proxy exit.
+   * mandatory - without it Yelp picks a location itself.
    * Paged with `page`; the page size is fixed at 10.
    *
    * Costs 2 credits.
@@ -1951,8 +1974,7 @@ var IndeedNamespace = class {
    * employment types, benefits, geocoded address, employer rating, applicant
    * count and the original ATS link.
    *
-   * Single response, no pagination. An unknown job key is a real 404 that
-   * scrape.do BILLS - take `job_id` from a search row.
+   * Single response, no pagination. An unknown job key is a real 404 and IS BILLED - take `job_id` from a search row.
    *
    * Costs 2 credits.
    */
@@ -1964,8 +1986,7 @@ var IndeedNamespace = class {
    * approval, overall and per-category ratings, reported salaries, open roles
    * and locations.
    *
-   * Single response, no pagination. An unknown company slug is a real 404
-   * that scrape.do BILLS.
+   * Single response, no pagination. An unknown company slug is a real 404 and IS BILLED.
    *
    * Costs 2 credits.
    */
@@ -2013,7 +2034,7 @@ var GlassdoorNamespace = class {
    * server-rendered reviews, AND reviews_url / salaries_url.
    *
    * THE CHAINING ENDPOINT: pass reviews_url / salaries_url back as `url` on
-   * reviews() and salaries() to halve the upstream fetches. `employer_id` or
+   * reviews() and salaries() to halve the lookups. `employer_id` or
    * `url` is required - `company` is cosmetic and does not satisfy it.
    *
    * Costs 1 credit. Single response, no pagination. Typically ~3-47s.
@@ -2337,7 +2358,7 @@ var SECNamespace = class {
    * filer had more.
    *
    * Costs 1 credit - including with `include_history`, which is the one call
-   * that can buy more than one upstream fetch.
+   * that can buy more than one lookup.
    */
   async filings(options) {
     return this.client._post("/api/v1/sec/filings", options);