scavio 0.24.1 → 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.1" : "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);