talordata-serp 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# TalorData JavaScript SDK
+
+A lightweight JavaScript SDK for the TalorData SERP API.
+
+Repository: [Talordata/talordata-serp-javascript](https://github.com/Talordata/talordata-serp-javascript)
+
+## Install
+
+```bash
+npm install talordata-serp
+```
+
+## Quick Start
+
+```javascript
+const { Client } = require("talordata-serp");
+
+async function main() {
+  const client = new Client({ apiToken: process.env.TALORDATA_API_TOKEN });
+
+  const result = await client.search({
+    engine: "google",
+    q: "car",
+  });
+
+  console.log(result.search_metadata?.status);
+  console.log(result.search_information?.query_displayed);
+}
+
+main().catch(console.error);
+```
+
+## Examples
+
+- `examples/basic-search.js`: basic `json=1` search example.
+- `examples/json-plus-html.js`: `json=2` example with both HTML and parsed JSON.
+- `examples/html-output.js`: `json=3` example that prints HTML output.
+
+You can also set the token once in your shell:
+
+```bash
+export TALORDATA_API_TOKEN=your_token
+```
+
+Then use the top-level helper:
+
+```javascript
+const talordata = require("talordata-serp");
+
+async function main() {
+  const result = await talordata.search({
+    engine: "google",
+    q: "car",
+  });
+
+  console.log(result);
+}
+
+main().catch(console.error);
+```
+
+## API Design
+
+- `new Client({ apiToken })`: create a reusable client.
+- `client.search(...)`: send a form-encoded `POST` request to `/serp/v1/request` and return the parsed result.
+- `client.searchJson(...)`: alias of `search(...)`.
+- `client.searchHtml(...)`: return the HTML string for `json=3`.
+- `client.rawSearch(...)`: return the raw HTTP response body.
+
+## JSON Modes
+
+- `json=1`: returns parsed JSON data. This is the default mode used by `client.search(...)`.
+- `json=2`: returns both `html` and `json`. The SDK automatically parses `data.json` into an object when possible.
+- `json=3`: returns HTML. The SDK unwraps the HTML string from the API response.
+
+## Example With URL
+
+```javascript
+const { Client } = require("talordata-serp");
+
+async function main() {
+  const client = new Client({ apiToken: process.env.TALORDATA_API_TOKEN });
+
+  const result = await client.search({
+    url: "https://www.google.com/search",
+    q: "car",
+    json: 1,
+  });
+
+  console.log(result);
+}
+
+main().catch(console.error);
+```
+
+## Notes
+
+- Auth uses the `Authorization: Bearer <token>` header.
+- Requests are sent as `application/x-www-form-urlencoded`.
+- Boolean params are normalized to `"1"` and `"0"` before sending.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "talordata-serp",
+  "version": "0.1.0",
+  "description": "JavaScript SDK for TalorData SERP API",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "talordata",
+    "serp",
+    "sdk",
+    "search"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Talordata/talordata-serp-javascript.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,184 @@
+const DEFAULT_BASE_URL = "https://serpapi.talordata.net";
+const REQUEST_PATH = "/serp/v1/request";
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+class TalorDataError extends Error {}
+
+class APITokenNotProvidedError extends TalorDataError {
+  constructor() {
+    super("Please provide `apiToken` or set the `TALORDATA_API_TOKEN` environment variable.");
+    this.name = "APITokenNotProvidedError";
+  }
+}
+
+class HTTPError extends TalorDataError {
+  constructor(statusCode, message, body = null) {
+    super(message);
+    this.name = "HTTPError";
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}
+
+function resolveToken(providedToken) {
+  return (
+    providedToken ||
+    process.env.TALORDATA_API_TOKEN ||
+    process.env.TALORDATA_SERP_API_TOKEN ||
+    null
+  );
+}
+
+function buildUrl(baseUrl, path) {
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+  const normalizedBaseUrl = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  return `${normalizedBaseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+function normalizeParams(params = {}) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (typeof value === "boolean") {
+      normalized[key] = value ? "1" : "0";
+      continue;
+    }
+    normalized[key] = String(value);
+  }
+  return normalized;
+}
+
+function unwrapPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return payload;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(payload, "data")) {
+    return payload;
+  }
+
+  const data = payload.data;
+  if (typeof data === "string") {
+    return data;
+  }
+
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const nextData = { ...data };
+    if (typeof nextData.json === "string") {
+      try {
+        nextData.json = JSON.parse(nextData.json);
+      } catch (_) {
+        // Keep the raw string when the backend does not return valid JSON.
+      }
+    }
+    return nextData;
+  }
+
+  return payload;
+}
+
+async function fromHttpResponse(response) {
+  const text = await response.text();
+  try {
+    const payload = JSON.parse(text);
+    return unwrapPayload(payload);
+  } catch (_) {
+    return text;
+  }
+}
+
+class Client {
+  constructor({ apiToken, apiKey, token, timeout = DEFAULT_TIMEOUT_MS, baseUrl = DEFAULT_BASE_URL } = {}) {
+    this.apiToken = resolveToken(apiToken || apiKey || token);
+    this.timeout = timeout;
+    this.baseUrl = baseUrl;
+  }
+
+  async request(method, path, params = {}, { apiToken, headers = {}, signal } = {}) {
+    const token = resolveToken(apiToken || this.apiToken);
+    if (!token) {
+      throw new APITokenNotProvidedError();
+    }
+
+    const requestHeaders = {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json, text/html;q=0.9, */*;q=0.8",
+      "User-Agent": "talordata-serp-javascript/0.1.0",
+      ...headers,
+    };
+
+    const init = {
+      method: method.toUpperCase(),
+      headers: requestHeaders,
+      body: new URLSearchParams(normalizeParams(params)),
+      signal: signal || AbortSignal.timeout(this.timeout),
+    };
+
+    const response = await fetch(buildUrl(this.baseUrl, path), init);
+    if (!response.ok) {
+      const body = await response.text();
+      throw new HTTPError(response.status, `HTTP ${response.status}`, body);
+    }
+    return response;
+  }
+
+  async search(params = {}, options = {}) {
+    const payload = { ...params };
+    if (!Object.prototype.hasOwnProperty.call(payload, "json")) {
+      payload.json = "1";
+    }
+    const response = await this.request("POST", REQUEST_PATH, payload, options);
+    return fromHttpResponse(response);
+  }
+
+  async searchJson(params = {}, options = {}) {
+    return this.search(params, options);
+  }
+
+  async searchHtml(params = {}, options = {}) {
+    const payload = { ...params, json: "3" };
+    const response = await this.request("POST", REQUEST_PATH, payload, options);
+    const result = await fromHttpResponse(response.clone());
+    if (typeof result === "string") {
+      return result;
+    }
+    return response.text();
+  }
+
+  async rawSearch(params = {}, options = {}) {
+    const response = await this.request("POST", REQUEST_PATH, params, options);
+    return response.text();
+  }
+}
+
+async function search(params = {}, options = {}) {
+  return new Client().search(params, options);
+}
+
+async function searchJson(params = {}, options = {}) {
+  return new Client().searchJson(params, options);
+}
+
+async function searchHtml(params = {}, options = {}) {
+  return new Client().searchHtml(params, options);
+}
+
+async function rawSearch(params = {}, options = {}) {
+  return new Client().rawSearch(params, options);
+}
+
+module.exports = {
+  APITokenNotProvidedError,
+  Client,
+  HTTPError,
+  TalorDataError,
+  rawSearch,
+  search,
+  searchHtml,
+  searchJson,
+};