Add support for request options

.github/workflows/build.yml

@@ -5,15 +5,15 @@ on: [push]
 jobs:
   build:
     name: "Deno tests and build npm files"
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
         uses: actions/checkout@v3
 
       - name: Setup Deno
-        uses: denoland/setup-deno@v1.1.1
+        uses: denoland/setup-deno@v2
         with:
-          deno-version: v1.x
+          deno-version: v2.x
 
       - name: Check formatting
         run: deno fmt --check
@@ -24,13 +24,13 @@ jobs:
       - name: Run tests
         env:
           SERPAPI_TEST_KEY: ${{ secrets.SERPAPI_TEST_KEY }}
-        run: deno task test:ci
+        run: deno task test
 
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18.x'  # Build files using a fixed node version
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "22.x" # Build files using a fixed node version
+          registry-url: "https://registry.npmjs.org"
 
       - name: Build npm files
         run: deno task npm
@@ -39,7 +39,7 @@ jobs:
         run: zip npm.zip ./npm -r
 
       - name: Upload build files for smoke tests
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: npm
           path: npm.zip
@@ -48,10 +48,29 @@ jobs:
   smoke-tests-commonjs:
     name: "Smoke tests (CommonJS)"
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [7.x, 8.x, 9.x, 10.x, 11.x, 12.x, 13.x, 14.x, 15.x, 16.x, 17.x, 18.x, 19.x]
+        node-version: [
+          7.x,
+          8.x,
+          9.x,
+          10.x,
+          11.x,
+          12.x,
+          13.x,
+          14.x,
+          15.x,
+          16.x,
+          17.x,
+          18.x,
+          19.x,
+          20.x,
+          21.x,
+          22.x,
+          23.x,
+          24.x,
+        ]
         include:
           - command: test
           - command: test:use-openssl-ca
@@ -63,16 +82,16 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          registry-url: 'https://registry.npmjs.org'
+          registry-url: "https://registry.npmjs.org"
 
       - name: Download build files
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: npm
 
@@ -90,22 +109,34 @@ jobs:
   smoke-tests-esm:
     name: "Smoke tests (ESM)"
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [14.x, 15.x, 16.x, 17.x, 18.x, 19.x]
+        node-version: [
+          14.x,
+          15.x,
+          16.x,
+          17.x,
+          18.x,
+          19.x,
+          20.x,
+          21.x,
+          22.x,
+          23.x,
+          24.x,
+        ]
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          registry-url: 'https://registry.npmjs.org'
+          registry-url: "https://registry.npmjs.org"
 
       - name: Download build files
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: npm
 

.github/workflows/release.yml

@@ -5,19 +5,19 @@ on:
     branches:
       - master
     paths:
-      - 'version.ts'
+      - "version.ts"
 
 jobs:
   release:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Deno
-        uses: denoland/setup-deno@v1.1.1
+        uses: denoland/setup-deno@v2
         with:
-          deno-version: v1.x
+          deno-version: v2.x
 
       - name: Check formatting
         run: deno fmt --check
@@ -28,13 +28,13 @@ jobs:
       - name: Run tests
         env:
           SERPAPI_TEST_KEY: ${{ secrets.SERPAPI_TEST_KEY }}
-        run: deno task test:ci
+        run: deno task test
 
       - name: Setup Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18.x'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "22.x"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Build npm files
         run: deno task npm

CONTRIBUTING.md

@@ -66,9 +66,8 @@ and you're good to go.
 
 ### Tests that require an API key
 
-- When testing functionality that hits either `localhost` or
-  `https://serpapi.com`, and requires an API key, you need to ensure your API
-  key is specified as an environment variable.
+- When testing functionality that requires an API key, you need to ensure your
+  API key is specified as an environment variable.
 - Create a `.env` file with the following contents, replacing `YOUR_API_KEY`
   with your API key for the appropriate environment.
 
@@ -91,10 +90,9 @@ it("getJson with api key from config", {
 ## Run tests
 
 ```bash
-deno task test         # Run tests that hit "localhost"
-deno task test:watch   # Run tests that hit "localhost" and in watch mode: https://deno.land/manual/getting_started/command_line_interface#watch-mode
-deno task test:cov     # Get test coverage by running tests that hit "localhost"
-deno task test:ci      # Run tests that hit "https://serpapi.com"
+deno task test         # Run tests
+deno task test:watch   # Run tests and in watch mode: https://deno.land/manual/getting_started/command_line_interface#watch-mode
+deno task test:cov     # Get test coverage by running tests
 ```
 
 ## Run examples on local source files

README.md

@@ -24,6 +24,8 @@ more.
 
 ```bash
 npm install serpapi
+# or if you prefer yarn
+yarn add serpapi
 ```
 
 ```js
@@ -114,6 +116,41 @@ await getJson({ engine: "google", q: "coffee" }); // uses the API key defined in
 await getJson({ engine: "google", api_key: API_KEY_2, q: "coffee" }); // API_KEY_2 will be used
 ```
 
+### Using a Proxy
+
+You can use a proxy by passing `requestOptions` with an `HttpsProxyAgent`
+instance. This can be done either globally through the config object or
+per-request in the parameters.
+
+First, install the required package:
+
+```bash
+npm install https-proxy-agent
+# or if you prefer yarn
+yarn add https-proxy-agent
+```
+
+Then use it in your code:
+
+```js
+import { config, getJson } from "serpapi";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+// Global configuration
+config.requestOptions = {
+  agent: new HttpsProxyAgent("http://proxy-server:port"),
+};
+
+// Or per-request configuration
+await getJson({
+  engine: "google",
+  q: "coffee",
+  requestOptions: {
+    agent: new HttpsProxyAgent("http://proxy-server:port"),
+  },
+});
+```
+
 ## Pagination
 
 Built-in pagination is not supported. Please refer to our pagination examples

deno.json

@@ -1,33 +1,22 @@
 {
   "tasks": {
     "docs:gen": "npx documentation readme src/serpapi.ts --section=Functions --shallow && deno fmt",
-    "test": "ENV_TYPE=local deno test tests/ --allow-env --allow-read --allow-net --fail-fast",
+    "test": "deno test tests/ --allow-env --allow-read --allow-net",
     "test:watch": "deno task test --watch",
     "test:cov": "rm -rf cov_profile && deno task test --coverage=cov_profile && deno coverage cov_profile",
-    "test:ci": "deno test tests/ --allow-env --allow-read --allow-net",
     "npm": "deno run -A scripts/build_npm.ts"
   },
   "fmt": {
-    "files": {
-      "exclude": ["npm/", "examples/node", "smoke_tests/"]
-    }
+    "exclude": ["npm/", "examples/node", "smoke_tests/"]
   },
   "lint": {
-    "files": {
-      "exclude": ["npm/", "examples/node", "smoke_tests/"]
-    }
+    "exclude": ["npm/", "examples/node", "smoke_tests/"]
   },
   "test": {
-    "files": {
-      "include": ["tests/"]
-    }
+    "include": ["tests/"]
   },
   "compilerOptions": {
-    "lib": [
-      "dom",
-      "dom.iterable",
-      "deno.ns"
-    ]
+    "lib": ["dom", "dom.iterable", "deno.ns"]
   },
   "lock": false
 }

examples/node/js_node_14_up/basic_example.js

@@ -7,6 +7,7 @@
  */
 
 import * as Dotenv from "dotenv";
+import process from "process";
 import { config, getJson } from "serpapi";
 
 Dotenv.config();

examples/node/js_node_14_up/pagination_example.js

@@ -7,6 +7,7 @@
  */
 
 import * as Dotenv from "dotenv";
+import process from "process";
 import { config, getJson } from "serpapi";
 
 Dotenv.config();

examples/node/js_node_7_up/basic_example.js

@@ -3,6 +3,7 @@
  */
 
 const Dotenv = require("dotenv");
+const process = require("process");
 const { config, getJson } = require("serpapi");
 
 Dotenv.config();

examples/node/js_node_7_up/pagination_example.js

@@ -6,6 +6,7 @@ const Dotenv = require("dotenv");
 const { config, getJson } = require("serpapi");
 const url = require("url");
 const qs = require("querystring");
+const process = require("process");
 
 Dotenv.config();
 config.api_key = process.env.API_KEY;

scripts/build_npm.ts

@@ -1,4 +1,4 @@
-import { build, emptyDir } from "https://deno.land/x/dnt@0.37.0/mod.ts";
+import { build, emptyDir } from "https://deno.land/x/dnt@0.40.0/mod.ts";
 import { version } from "../version.ts";
 
 await emptyDir("./npm");

smoke_tests/commonjs/commonjs.js

@@ -3,6 +3,7 @@
  */
 
 const Dotenv = require("dotenv");
+const process = require("process");
 const {
   config,
   getJson,

smoke_tests/esm/esm.js

@@ -7,6 +7,7 @@
  */
 
 import Dotenv from "dotenv";
+import process from "process";
 import {
   config,
   getAccount,

src/config.ts

@@ -1,7 +1,11 @@
+import http from "node:http";
+
 export type Config = {
   api_key: string | null;
   timeout: number;
+  requestOptions?: http.RequestOptions;
 };
+
 export const config: Config = {
   api_key: null,
   timeout: 60000,