@specstream/sdk 1.2.0 → 1.3.2

package/README.md

@@ -1,6 +1,8 @@
 # @specstream/sdk
 
-TypeScript client for [SpecStream](https://specstream.ai), the live web data engine for teams and agents. Describe the list you need in plain words; SpecStream reads the web where those things live, hands back only the matches, each with the page it came from, and you pay for each result delivered.
+TypeScript client for [SpecStream](https://specstream.ai), the live web data engine for teams and agents. Describe the list you need in plain words; SpecStream reads the web where those things live, hands back only the matches, and you pay for each result delivered.
+
+Source URL and read time on every value.
 
 The client has no runtime dependencies and needs Node 22 or newer. It uses the same account, permissions, projects and balance as the workspace.
 
@@ -10,6 +12,29 @@ npm install @specstream/sdk
 
 Create an API key under **Agents & API** in your SpecStream workspace and keep it in the environment: `SPECSTREAM_API_KEY`.
 
+## Search API and Extract API
+
+SpecStream has three products: Search API, Extract API and Deep Search. The first two take one call at a flat price, with no quote or approval. The sections after this one cover Deep Search.
+
+`client.webSearch` calls the [Search API](https://specstream.ai/docs/search-api), `GET /v1/web-search`, at $5 per 1,000 searches. It is the most accurate web search API in the world ([benchmarks](https://specstream.ai/benchmarks)) and answers from the live web in a few seconds. Write `q` in everyday words, in any language.
+
+`client.extractPages` calls the [Extract API](https://specstream.ai/docs/extract-api), `POST /v1/extract`, at $0.80 per 1,000 pages. It takes up to 20 URLs a call, reads web pages, PDF, Word and Excel, and returns each one's main text as `markdown` (the default) or `text`. A page with no text is free.
+
+```ts
+import { Client } from "@specstream/sdk";
+
+const client = new Client({ apiKey: process.env.SPECSTREAM_API_KEY! });
+
+const search = await client.webSearch({ q: "What is the latest stable release of PostgreSQL?" });
+console.log(search.answer?.value, search.answer?.page);
+
+const extract = await client.extractPages({
+  urls: search.sources.slice(0, 5).map((source) => source.url),
+  format: "markdown",
+});
+for (const page of extract.results) console.log(page.url, page.status, page.text);
+```
+
 ## Read a request, get the price
 
 ```ts
@@ -59,7 +84,7 @@ If the response is lost, `getCapacityRequest(savedRequestKey)` returns the same
 
 ## Pricing
 
-New accounts start with $10 of work for 30 days, no card. A delivered result costs 10 cents, 30 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 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).
 
 ## Links
 

package/dist/index.d.ts

@@ -55,6 +55,17 @@ export declare class Client {
         "limit"?: number;
         "cursor"?: string;
     }): Promise<Schemas["WorkspaceSearchPage"]>;
+    webSearch(query: {
+        "q": string;
+        "passages"?: boolean;
+    }): Promise<Schemas["WebSearchPage"]>;
+    extractPages(request: Schemas["ExtractRequest"]): Promise<Schemas["ExtractPage"]>;
+    webSearchAnswers(query?: {
+        "q"?: string;
+        "limit"?: number;
+        "cursor"?: string;
+    }): Promise<Schemas["WebSearchAnswerPage"]>;
+    webSearchAnswer(answerId: string): Promise<Schemas["WebSearchAnswer"]>;
     workspaceListNotifications(query?: {
         "tab"?: "all" | "unread" | "archived";
         "limit"?: number;
@@ -152,9 +163,20 @@ export declare class Client {
         "project_id"?: string;
         "cursor"?: string;
         "limit"?: number;
-    }): Promise<{
+        "format"?: "json" | "markdown" | "csv";
+    }): Promise<({
         [key: string]: unknown;
-    }>;
+    } | {
+        "format": "markdown" | "csv";
+        "columns": Array<{
+            "column_id": string;
+            "label": string;
+        }>;
+        "table": string;
+        "find_id"?: (string | null);
+        "accepted_count"?: number;
+        "next_cursor"?: (string | null);
+    })>;
     getCapacityExecution(findId: string): Promise<Schemas["CommerceData"]>;
     createCapacityFunding(request: Schemas["CapacityFundingRequest"]): Promise<Schemas["CapacityFundingData"]>;
     getCapacityFunding(fundingId: string): Promise<Schemas["CapacityFundingData"]>;
@@ -280,6 +302,7 @@ export declare class Client {
         "field_id"?: string;
     }): Promise<Schemas["RelationshipData"]>;
     workspaceSaveRelationships(collectionId: string, request: Schemas["RelationshipSelection"]): Promise<Schemas["RelationshipData"]>;
+    workspaceShareCollection(collectionId: string, request: Schemas["CollectionShareInput"]): Promise<Schemas["CollectionShareData"]>;
     workspaceReportResult(collectionId: string, request: Schemas["ResultReportInput"]): Promise<Schemas["ResultReportData"]>;
     listRequestTemplates(query?: {
         "record_type"?: string;

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;
@@ -220,6 +231,34 @@ export class Client {
             path += "?" + queryString.toString();
         return this.request("GET", path);
     }
+    webSearch(query) {
+        let path = `/v1/web-search`;
+        const queryString = new URLSearchParams();
+        for (const [key, value] of Object.entries(query))
+            if (value !== undefined && value !== null)
+                queryString.set(key, String(value));
+        if (queryString.size)
+            path += "?" + queryString.toString();
+        return this.request("GET", path);
+    }
+    extractPages(request) {
+        let path = `/v1/extract`;
+        return this.request("POST", path, request);
+    }
+    webSearchAnswers(query = {}) {
+        let path = `/v1/web-search/answers`;
+        const queryString = new URLSearchParams();
+        for (const [key, value] of Object.entries(query))
+            if (value !== undefined && value !== null)
+                queryString.set(key, String(value));
+        if (queryString.size)
+            path += "?" + queryString.toString();
+        return this.request("GET", path);
+    }
+    webSearchAnswer(answerId) {
+        let path = `/v1/web-search/answers/${encodeURIComponent(answerId)}`;
+        return this.request("GET", path);
+    }
     workspaceListNotifications(query = {}) {
         let path = `/v1/workspace/notifications`;
         const queryString = new URLSearchParams();
@@ -805,6 +844,10 @@ export class Client {
         let path = `/v1/workspace/collections/${encodeURIComponent(collectionId)}/relationships`;
         return this.request("PUT", path, request);
     }
+    workspaceShareCollection(collectionId, request) {
+        let path = `/v1/workspace/collections/${encodeURIComponent(collectionId)}/share`;
+        return this.request("POST", path, request);
+    }
     workspaceReportResult(collectionId, request) {
         let path = `/v1/workspace/collections/${encodeURIComponent(collectionId)}/reports`;
         return this.request("POST", path, request);
@@ -980,21 +1023,29 @@ export class Client {
             Authorization: token,
             Accept: "application/json",
             "Content-Type": "application/json",
-            "User-Agent": "specstream-typescript/1.2.0",
+            "User-Agent": "specstream-typescript/1.3.2",
         };
     }
     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

@@ -6,6 +6,7 @@ export interface Schemas {
         "worded_evidence"?: ({
             [key: string]: unknown;
         } | null);
+        "unconfirmed"?: (Array<string> | null);
         "lineage"?: (Schemas["MatchLineage"] | null);
         "spec_version"?: "accepted_row.v1";
         "entity_id": string;
@@ -267,6 +268,7 @@ export interface Schemas {
         "share_percent": number;
         "months": number;
         "clearing_days": number;
+        "yearly_clearing_days": number;
         "pending_cents": number;
         "payable_cents": number;
         "paid_cents": number;
@@ -456,6 +458,20 @@ export interface Schemas {
         "source_collection_ids"?: (Array<string> | null);
         "bbox"?: (Array<unknown> | null);
     };
+    "CollectionShareData": {
+        "id": string;
+        "snapshot_id": string;
+        "public_url": string;
+        "created_at": string;
+        "expires_at"?: (string | null);
+        "revoked": boolean;
+        "allow_export": boolean;
+        "row_count": number;
+    };
+    "CollectionShareInput": {
+        "expires_days"?: (number | null);
+        "allow_export"?: boolean;
+    };
     "CombineCollectionsInput": {
         "request_id": string;
         "name": string;
@@ -505,6 +521,12 @@ export interface Schemas {
         "name": string;
         "project_id"?: (string | null);
     };
+    "CoreEntity": {
+        "name": string;
+        "url": string;
+        "description": string;
+        "request": string;
+    };
     "CountComparison": {
         "op": "gte" | "gt" | "lte" | "lt" | "eq" | "ne";
         "value": number;
@@ -649,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"];
     };
@@ -691,6 +713,25 @@ export interface Schemas {
     "ExportRequest": {
         "format": Schemas["ExportFormat"];
     };
+    "ExtractPage": {
+        "request_id": string;
+        "results": Array<Schemas["ExtractedPage"]>;
+        "took_ms": number;
+        "price_usd": number;
+    };
+    "ExtractRequest": {
+        "urls": Array<string>;
+        "format"?: "markdown" | "text";
+    };
+    "ExtractedPage": {
+        "url": string;
+        "status": "ok" | "blocked" | "not_found" | "empty" | "unsupported" | "invalid_url" | "failed";
+        "title": (string | null);
+        "text": string;
+        "published": (string | null);
+        "read_from"?: ("live" | "site" | "archive" | null);
+        "captured_at"?: (string | null);
+    };
     "FieldObservation": {
         "entity_id": string;
         "field_id": string;
@@ -1185,6 +1226,7 @@ export interface Schemas {
     };
     "ParseResult": {
         "retained"?: (Schemas["RetainedRequest"] | null);
+        "core_entity"?: (Schemas["CoreEntity"] | null);
         "grading"?: (Schemas["ReadingGrade"] | null);
         "understanding"?: (Schemas["Understanding"] | null);
         "decision_id"?: (string | null);
@@ -2218,6 +2260,126 @@ export interface Schemas {
         "expirationTime"?: ((number) | null);
         "name": string;
     };
+    "WebSearchAnswer": {
+        "id"?: (string | null);
+        "request_id": string;
+        "query": string;
+        "kind": "list" | "fact";
+        "columns": Array<string>;
+        "answer": (Schemas["WebSearchValue"] | null);
+        "rows": Array<Schemas["WebSearchRow"]>;
+        "sources": Array<Schemas["WebSearchSource"]>;
+        "handoff": (Schemas["WebSearchHandoff"] | null);
+        "took_ms": number;
+        "price_usd": number;
+        "passages"?: (Array<Schemas["WebSearchPassage"]> | null);
+        "request": string;
+        "created_at": string;
+    };
+    "WebSearchAnswerPage": {
+        "results": Array<Schemas["WebSearchAnswerSummary"]>;
+        "next_cursor": (string | null);
+    };
+    "WebSearchAnswerSummary": {
+        "id": string;
+        "request": string;
+        "created_at": string;
+        "rows": number;
+        "answer": (string | null);
+        "source"?: (string | null);
+        "sources"?: Array<Schemas["WebSearchCited"]>;
+        "list": boolean;
+        "kind": "list" | "fact";
+    };
+    "WebSearchBatchPage": {
+        "results": Array<Schemas["WebSearchBatchResult"]>;
+        "took_ms": number;
+        "price_usd": number;
+    };
+    "WebSearchBatchRequest": {
+        "questions": Array<Schemas["WebSearchQuestion"]>;
+    };
+    "WebSearchBatchResult": {
+        "request_id": string;
+        "status": number;
+        "data": (Schemas["WebSearchPage"] | null);
+        "error": (Schemas["ErrorBody"] | null);
+        "retry_after_s"?: (number | null);
+    };
+    "WebSearchCall": {
+        "method": "POST";
+        "path": "/v1/parse";
+        "body": {
+            [key: string]: unknown;
+        };
+    };
+    "WebSearchCited": {
+        "url": string;
+        "title": string;
+        "site": string;
+    };
+    "WebSearchHandoff": {
+        "line": string;
+        "request": string;
+        "rows_estimated": number;
+        "rows_basis": "request" | "page" | "seen";
+        "count_page": (string | null);
+        "next": Schemas["WebSearchNext"];
+    };
+    "WebSearchNext": {
+        "tool": "compile";
+        "arguments": {
+            [key: string]: unknown;
+        };
+        "http": Schemas["WebSearchCall"];
+    };
+    "WebSearchPage": {
+        "id"?: (string | null);
+        "request_id": string;
+        "query": string;
+        "kind": "list" | "fact";
+        "columns": Array<string>;
+        "answer": (Schemas["WebSearchValue"] | null);
+        "rows": Array<Schemas["WebSearchRow"]>;
+        "sources": Array<Schemas["WebSearchSource"]>;
+        "handoff": (Schemas["WebSearchHandoff"] | null);
+        "took_ms": number;
+        "price_usd": number;
+        "passages"?: (Array<Schemas["WebSearchPassage"]> | null);
+    };
+    "WebSearchPassage": {
+        "url": string;
+        "title": string;
+        "text": string;
+    };
+    "WebSearchQuestion": {
+        "q": string;
+        "id"?: (string | null);
+    };
+    "WebSearchRow": {
+        "name": string;
+        "page": string;
+        "snippet": string;
+        "probability": number;
+        "fields": {
+            [key: string]: Schemas["WebSearchValue"];
+        };
+        "sources"?: Array<number>;
+    };
+    "WebSearchSource": {
+        "url": string;
+        "title": string;
+        "site": string;
+        "snippet": string;
+        "cited": boolean;
+        "published"?: (string | null);
+    };
+    "WebSearchValue": {
+        "value": string;
+        "page": string;
+        "seen_at"?: (string | null);
+        "confirmed"?: (boolean | null);
+    };
     "WebSourceCell": {
         "source_url": string;
         "response_sha256": string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specstream/sdk",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "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",