@specstream/sdk 1.3.0 → 1.3.3

package/README.md

@@ -35,6 +35,36 @@ const extract = await client.extractPages({
 for (const page of extract.results) console.log(page.url, page.status, page.text);
 ```
 
+## Drop-in for the API you already call
+
+SpecStream answers calls written for these search APIs at its own address, in each API's own reply shape. To switch, change the base address and the key. Each search call is one Search API web search on your SpecStream key: $0.005 for up to 10 results ($5 per 1,000 searches), and each 10 results more in the same call add $0.006.
+
+| API you call | Base address you have | SpecStream address | Where the SpecStream key goes |
+| --- | --- | --- | --- |
+| Tavily | `https://api.tavily.com` | `https://api.specstream.ai/tavily` | Bearer token or `api_key` |
+| Exa | `https://api.exa.ai` | `https://api.specstream.ai/exa` | `x-api-key` or Bearer token |
+| Brave Search API | `https://api.search.brave.com` | `https://api.specstream.ai` | `X-Subscription-Token` |
+| Serper | `https://google.serper.dev` | `https://api.specstream.ai/serper` | `X-API-KEY` |
+| Bing Web Search API v7 | `https://api.bing.microsoft.com/v7.0/search` | `https://api.specstream.ai/v7.0/search` | `Ocp-Apim-Subscription-Key` |
+| Google Custom Search JSON API | `https://www.googleapis.com` or `https://customsearch.googleapis.com` | `https://api.specstream.ai` | `key=` (`cx` is accepted and not used) |
+| SearXNG (JSON) | your instance address | `https://api.specstream.ai/searxng/<key>` | in the address, `key=`, `X-API-Key` or Bearer token |
+| Firecrawl v2 | `https://api.firecrawl.dev` | `https://api.specstream.ai/firecrawl` | Bearer token |
+
+The official Tavily and Exa Python SDKs take the address as an argument:
+
+```python
+import os
+from tavily import TavilyClient
+from exa_py import Exa
+
+tavily = TavilyClient(api_key=os.environ["SPECSTREAM_API_KEY"], api_base_url="https://api.specstream.ai/tavily")
+exa = Exa(api_key=os.environ["SPECSTREAM_API_KEY"], base_url="https://api.specstream.ai/exa")
+```
+
+- A Brave call that sends no `count` is priced as 20 results ($0.011). Send `count=10` for $0.005.
+- A Firecrawl `/v2/scrape` call is one Extract API page at $0.0008. The Firecrawl JavaScript SDK works with this address; the Firecrawl Python SDK does not yet.
+- Each route's request and reply fields: [specstream.ai/agents.md](https://specstream.ai/agents.md). Create a key under **Agents & API** at [specstream.ai/workspace](https://specstream.ai/workspace). New accounts start with $10 of credit, no card.
+
 ## Read a request, get the price
 
 ```ts
@@ -84,7 +114,7 @@ If the response is lost, `getCapacityRequest(savedRequestKey)` returns the same
 
 ## Pricing
 
-New accounts start with $10 of credit for 30 days, no card. The Search API costs $5 per 1,000 searches and the Extract API $0.80 per 1,000 pages. In Deep Search, a delivered result costs 5 cents, 15 cents or $1 depending on how many facts it carries. No result, no charge. See [pricing](https://specstream.ai/pricing).
+New accounts start with $10 of credit, no card. The Search API costs $5 per 1,000 searches and the Extract API $0.80 per 1,000 pages. In Deep Search, a delivered result costs 5 cents, 15 cents or $1 depending on how many facts it carries. No result, no charge. See [pricing](https://specstream.ai/pricing).
 
 ## Links
 

package/dist/index.js

@@ -56,6 +56,17 @@ export function assertFamily(entityType) {
     }
     return entityType;
 }
+const RETRY_AFTER_MAX_MS = 10_000;
+/** Milliseconds to wait before the one retry of a 503 that names its Retry-After, or null. */
+function retryAfterMs(response) {
+    if (response.status !== 503)
+        return null;
+    const value = (response.headers?.get("retry-after") || "").trim();
+    if (!value)
+        return null;
+    const ms = /^\d+(\.\d+)?$/.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+    return Number.isFinite(ms) && ms >= 0 && ms <= RETRY_AFTER_MAX_MS ? ms : null;
+}
 export class Client {
     apiKey;
     baseUrl;
@@ -1012,21 +1023,29 @@ export class Client {
             Authorization: token,
             Accept: "application/json",
             "Content-Type": "application/json",
-            "User-Agent": "specstream-typescript/1.3.0",
+            "User-Agent": "specstream-typescript/1.3.3",
         };
     }
     async request(method, path, body) {
         const url = this.baseUrl + path;
+        const send = () => this.fetchFn(url, {
+            method,
+            headers: this.headers(),
+            redirect: "error",
+            signal: AbortSignal.timeout(this.timeoutMs),
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
         let response;
         let text;
         try {
-            response = await this.fetchFn(url, {
-                method,
-                headers: this.headers(),
-                redirect: "error",
-                signal: AbortSignal.timeout(this.timeoutMs),
-                body: body === undefined ? undefined : JSON.stringify(body),
-            });
+            response = await send();
+            const wait = retryAfterMs(response);
+            if (wait !== null) {
+                // The server did nothing and names when to ask again: ask once more.
+                await response.body?.cancel();
+                await new Promise((resolve) => setTimeout(resolve, wait));
+                response = await send();
+            }
             text = await response.text();
         }
         catch (error) {

package/dist/work-types.d.ts

@@ -671,7 +671,7 @@ export interface Schemas {
             [key: string]: unknown;
         };
     };
-    "ErrorCode": "unsupported_query" | "unsupported_predicate" | "unsupported_entity_family" | "ambiguous_geo" | "capability_pending" | "source_blocked" | "challenge_page" | "unquoted_plan" | "compiler_unavailable" | "parse_failed" | "payments_not_live" | "capacity" | "kill_switch" | "internal_failure" | "plan_required" | "invalid_token";
+    "ErrorCode": "unsupported_query" | "unsupported_predicate" | "unsupported_entity_family" | "ambiguous_geo" | "capability_pending" | "source_blocked" | "challenge_page" | "unquoted_plan" | "missing_api_key" | "owner_only" | "compiler_unavailable" | "parse_failed" | "payments_not_live" | "capacity" | "kill_switch" | "internal_failure" | "plan_required" | "invalid_token" | "insufficient_balance";
     "ErrorEnvelope": {
         "error": Schemas["ErrorBody"];
     };
@@ -713,6 +713,10 @@ export interface Schemas {
     "ExportRequest": {
         "format": Schemas["ExportFormat"];
     };
+    "ExtractHtml": {
+        "html": string;
+        "url"?: (string | null);
+    };
     "ExtractPage": {
         "request_id": string;
         "results": Array<Schemas["ExtractedPage"]>;
@@ -720,16 +724,17 @@ export interface Schemas {
         "price_usd": number;
     };
     "ExtractRequest": {
-        "urls": Array<string>;
+        "urls"?: Array<string>;
+        "pages"?: Array<Schemas["ExtractHtml"]>;
         "format"?: "markdown" | "text";
     };
     "ExtractedPage": {
-        "url": string;
+        "url": (string | null);
         "status": "ok" | "blocked" | "not_found" | "empty" | "unsupported" | "invalid_url" | "failed";
         "title": (string | null);
         "text": string;
         "published": (string | null);
-        "read_from"?: ("live" | "site" | "archive" | null);
+        "read_from"?: ("live" | "site" | "archive" | "html" | null);
         "captured_at"?: (string | null);
     };
     "FieldObservation": {
@@ -1027,6 +1032,7 @@ export interface Schemas {
         "project_id": (string | null);
         "spend_cap_cents": number;
         "expires_at": (string | null);
+        "zero_retention": boolean;
     };
     "KeyCreateRequest": {
         "name"?: string;
@@ -1034,6 +1040,7 @@ export interface Schemas {
         "project_id"?: (string | null);
         "spend_cap_cents"?: number;
         "expires_in_days"?: number;
+        "zero_retention"?: boolean;
     };
     "KeyListItem": {
         "key_id": string;
@@ -1045,6 +1052,10 @@ export interface Schemas {
         "spend_cap_cents": number;
         "expires_at": (string | null);
         "last_used_at": (string | null);
+        "zero_retention": boolean;
+    };
+    "KeyUpdateRequest": {
+        "zero_retention": boolean;
     };
     "LineagePage": {
         "finds": Array<Schemas["FindLineage"]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specstream/sdk",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "TypeScript client for building lead lists and company lists from the live web. Every match comes with its source, priced before it runs.",
   "type": "module",
   "main": "./dist/index.js",