@openserp/sdk 0.1.0 → 0.1.2

package/README.md

@@ -4,9 +4,37 @@
 [![npm downloads](https://img.shields.io/npm/dm/@openserp/sdk.svg)](https://www.npmjs.com/package/@openserp/sdk)
 [![license](https://img.shields.io/npm/l/@openserp/sdk.svg)](https://github.com/karust/openserp/blob/master/LICENSE)
 
+```bash
+npm install @openserp/sdk
+```
+
+Cloud:
+
+```ts
+import { OpenSERP } from "@openserp/sdk";
+
+const client = new OpenSERP({ apiKey: process.env.OPENSERP_KEY });
+const { results } = await client.search({ engine: "google", text: "openserp" });
+
+console.log(results[0]?.title, results[0]?.url);
+```
+
+Self-hosted:
+
+```ts
+import { OpenSERP } from "@openserp/sdk";
+
+const client = new OpenSERP({ baseUrl: "http://localhost:7000" });
+const { results } = await client.search({ engine: "bing", text: "openserp" });
+
+console.log(results[0]?.title, results[0]?.url);
+```
+
 Universal TypeScript / JavaScript SDK for the **OpenSERP** multi-engine SERP API — Google, Bing, Yandex, Baidu, DuckDuckGo, and Ecosia results in a single call. Works against the self-hosted [open source server](https://github.com/karust/openserp) and against [OpenSERP Cloud](https://openserp.org/cloud) with the same code.
 
-Use it for AI grounding, RAG pipelines, LLM tool use, SEO monitoring, competitor analysis, and search-powered automations. Open-source alternative to SerpAPI and DataForSEO.
+Use it for AI grounding, RAG pipelines, LLM tool use, agent tool use, LangChain / LlamaIndex integrations, SEO rank tracking, competitor analysis, and search-powered automations. Open-source alternative to SerpAPI, DataForSEO, ScrapingBee, Bright Data SERP, Oxylabs SERP, and Zenserp.
+
+> Also available for Python: [`openserp`](https://pypi.org/project/openserp/) ([source](https://github.com/karust/openserp/tree/master/integrations/sdk-python)).
 
 > **Alpha — the API may change before `1.0.0`.** Pin a version in production.
 
@@ -22,7 +50,6 @@ Use it for AI grounding, RAG pipelines, LLM tool use, SEO monitoring, competitor
 - [Telemetry](#telemetry)
 - [Error handling](#error-handling)
 - [Retry hook](#retry-hook)
-- [Edge runtimes](#edge-runtimes)
 - [Use cases](#use-cases)
 - [Development](#development)
 
@@ -162,11 +189,7 @@ await client.enginesStatus();
 await client.enginesCapabilities();
 ```
 
-The backend is inferred from `baseUrl` and `apiKey`. Override explicitly when needed:
-
-```ts
-client.config.backend = "oss";
-```
+The backend is inferred from `baseUrl` and `apiKey`. Pass `backend: "oss"` or `backend: "cloud"` to the constructor to override.
 
 ## Telemetry
 
@@ -204,65 +227,41 @@ try {
 The SDK does not apply a retry policy. Provide a hook when you want one:
 
 ```ts
-const client = new OpenSERP({
-  baseUrl: "http://localhost:7000",
-  retry: (err, attempt) => {
-    return err instanceof SERPError && err.status >= 500 && attempt < 2;
-  },
-});
-```
-
-## Edge runtimes
+import { OpenSERP, SERPError } from "@openserp/sdk";
 
-The SDK uses global `fetch` and has no Node-only runtime dependency. It runs on Node, Bun, Deno, Cloudflare Workers, and Vercel Edge.
+const RETRYABLE = new Set([408, 429, 500, 502, 503]);
 
-Cloudflare Workers:
-
-```ts
-import { OpenSERP } from "@openserp/sdk";
-
-export default {
-  async fetch(_request: Request, env: { OPENSERP_KEY: string }) {
-    const client = new OpenSERP({ apiKey: env.OPENSERP_KEY });
-    const results = await client.fastSearch({ text: "openserp" });
-    return Response.json(results);
+const client = new OpenSERP({
+  apiKey: process.env.OPENSERP_KEY,
+  retry: async (err, attempt) => {
+    if (attempt >= 2 || !(err instanceof SERPError) || !RETRYABLE.has(err.status)) {
+      return false;
+    }
+    const wait = Math.min(2 ** attempt * 250, 8_000) + Math.random() * 250;
+    await new Promise((r) => setTimeout(r, wait));
+    return true;
   },
-};
-```
-
-Vercel Edge:
-
-```ts
-import { OpenSERP } from "@openserp/sdk";
-
-export const runtime = "edge";
-
-export async function GET() {
-  const client = new OpenSERP({ apiKey: process.env.OPENSERP_KEY });
-  return Response.json(await client.search({ engine: "google", text: "openserp" }));
-}
+});
 ```
 
 ## Use cases
 
 - **AI grounding / RAG** — feed top-N search results into an LLM prompt (OpenAI, Anthropic, Ollama) for up-to-date answers.
-- **LLM tool use** — expose `client.search` as a tool to your agent, or use the dedicated [`@openserp/mcp`](https://www.npmjs.com/package/@openserp/mcp) server in Claude Desktop, Cursor, Cline, and Windsurf.
+- **LLM tool use** — expose `client.search` as a tool to your agent.
 - **SEO monitoring** — daily rank tracking across multiple engines and regions, export to Sheets or Notion.
 - **Competitor analysis** — weekly diff of top-10 results for a keyword set.
-- **Automations** — drop the [`n8n-nodes-openserp`](https://www.npmjs.com/package/n8n-nodes-openserp) node into a workflow.
 - **Data pipelines** — stream SERPs to ClickHouse, BigQuery, or a DataFrame for NLP on snippets.
 
 ## Development
 
 ```bash
-corepack enable
-corepack pnpm install
-corepack pnpm test
-corepack pnpm build
+pnpm install
+pnpm test
+pnpm build
 ```
 
 Regenerate OSS API types after changing `openserp/docs/openapi.yaml`:
 
 ```bash
-corepack pnpm generate:types
+pnpm generate:types
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openserp/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript/JavaScript SDK for the OpenSERP self-hosted server and OpenSERP Cloud.",
   "type": "module",
   "license": "MIT",
@@ -8,8 +8,7 @@
   "homepage": "https://openserp.org",
   "repository": {
     "type": "git",
-    "url": "https://github.com/karust/openserp.git",
-    "directory": "integrations/sdk-js"
+    "url": "git+https://github.com/karust/openserp.git"
   },
   "bugs": {
     "url": "https://github.com/karust/openserp/issues"
@@ -17,15 +16,40 @@
   "keywords": [
     "openserp",
     "serp",
+    "serp-api",
     "search",
+    "search-api",
+    "google-search",
+    "google-search-api",
     "google",
     "bing",
     "yandex",
     "baidu",
     "duckduckgo",
     "ecosia",
+    "scraper",
+    "scraping",
+    "web-scraping",
+    "serpapi",
+    "serpapi-alternative",
     "seo",
-    "ai-grounding"
+    "rank-tracking",
+    "rank-tracker",
+    "keyword-research",
+    "ai",
+    "ai-grounding",
+    "rag",
+    "llm",
+    "llm-tools",
+    "agent",
+    "agent-tools",
+    "tool-use",
+    "openai",
+    "anthropic",
+    "mcp",
+    "typescript",
+    "nodejs",
+    "edge-runtime"
   ],
   "sideEffects": false,
   "exports": {