@specstream/langchain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecStream SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @specstream/langchain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[SpecStream](https://specstream.ai) is the live web data engine for teams and agents. One platform to build, search, extract, enrich, map, and monitor data across the entire web.
+
+Ask for any dataset in plain words, and SpecStream builds it from the entire live web: every match found, extracted and enriched into structured records, then monitored for change. It runs through the API and MCP, and inside Sheets, CRMs, Slack, n8n, Zapier and the other tools teams already use.
+
+Source URL and read time on every value.
+
+Three products:
+
+1. Search API: `GET /v1/web-search`, $5 per 1,000 searches. The most accurate web search API in the world (scores and method: https://specstream.ai/benchmarks).
+2. Extract API: `POST /v1/extract`, up to 20 URLs a call (web pages, PDF, Word, Excel), $0.80 per 1,000 pages. A page with no text is not charged.
+3. Deep Search: Ask in plain words. Get every match on the live web, in structured rows. Priced per row.
+
+## Install
+
+```bash
+npm install @specstream/langchain @langchain/core
+export SPECSTREAM_API_KEY=ss_live_...   # Agents & API in your SpecStream workspace
+```
+
+A free account comes with $10 of credit to use within 30 days and needs no card: [specstream.ai](https://specstream.ai/signup).
+
+## Tools
+
+Both tools are LangChain `StructuredTool` classes, built like `@langchain/tavily`.
+
+| Tool | Name | What it does | Cost |
+| --- | --- | --- | --- |
+| `SpecStreamSearch` | `specstream_search` | Calls `GET /v1/web-search` and returns the answer, matching rows and ranked sources, with page passages when `passages: true` | $5 per 1,000 searches |
+| `SpecStreamExtract` | `specstream_extract` | Calls `POST /v1/extract` and returns the main text, title and published date of 1 to 20 web pages, PDF, Word or Excel files | $0.80 per 1,000 pages (a page with no text is free) |
+
+Each tool takes `specstreamApiKey` (default: the `SPECSTREAM_API_KEY` environment variable), `apiBaseUrl`, `name` and `description`. A failed call returns `{ error }` to the model.
+
+MIT licensed.

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export type { SpecStreamSearchAPIRetrieverFields } from "./specstream-search.js";
+export { SpecStreamSearch } from "./specstream-search.js";
+export type { SpecStreamExtractAPIRetrieverFields } from "./specstream-extract.js";
+export { SpecStreamExtract } from "./specstream-extract.js";
+export type { SpecStreamAPIWrapperParams, SpecStreamExtractParams, SpecStreamExtractResponse, SpecStreamExtractResult, SpecStreamSearchParams, SpecStreamSearchResponse, SpecStreamSource, } from "./utils.js";
+export { SpecStreamSearchAPIWrapper, SpecStreamExtractAPIWrapper } from "./utils.js";

package/dist/cjs/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecStreamExtractAPIWrapper = exports.SpecStreamSearchAPIWrapper = exports.SpecStreamExtract = exports.SpecStreamSearch = void 0;
+var specstream_search_js_1 = require("./specstream-search.js");
+Object.defineProperty(exports, "SpecStreamSearch", { enumerable: true, get: function () { return specstream_search_js_1.SpecStreamSearch; } });
+var specstream_extract_js_1 = require("./specstream-extract.js");
+Object.defineProperty(exports, "SpecStreamExtract", { enumerable: true, get: function () { return specstream_extract_js_1.SpecStreamExtract; } });
+var utils_js_1 = require("./utils.js");
+Object.defineProperty(exports, "SpecStreamSearchAPIWrapper", { enumerable: true, get: function () { return utils_js_1.SpecStreamSearchAPIWrapper; } });
+Object.defineProperty(exports, "SpecStreamExtractAPIWrapper", { enumerable: true, get: function () { return utils_js_1.SpecStreamExtractAPIWrapper; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/specstream-extract.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod/v3";
+import { CallbackManagerForToolRun } from "@langchain/core/callbacks/manager";
+import { StructuredTool, ToolParams } from "@langchain/core/tools";
+import { InferInteropZodOutput } from "@langchain/core/utils/types";
+import { SpecStreamExtractAPIWrapper, type SpecStreamExtractResponse } from "./utils.js";
+/**
+ * Options for the SpecStreamExtract tool.
+ */
+export type SpecStreamExtractAPIRetrieverFields = ToolParams & {
+    /** The base URL of the SpecStream API. @default "https://api.specstream.ai" */
+    apiBaseUrl?: string;
+    /** The API key. Defaults to the `SPECSTREAM_API_KEY` environment variable. */
+    specstreamApiKey?: string;
+    /** Output format of the page text. Takes precedence over the call parameter. */
+    format?: "markdown" | "text";
+    /** Replace the tool name. */
+    name?: string;
+    /** Replace the tool description. */
+    description?: string;
+    /** Use a custom API wrapper, for example in tests. */
+    apiWrapper?: SpecStreamExtractAPIWrapper;
+};
+declare const inputSchema: z.ZodObject<{
+    urls: z.ZodArray<z.ZodString, "many">;
+    format: z.ZodOptional<z.ZodEnum<["markdown", "text"]>>;
+}, "strip", z.ZodTypeAny, {
+    urls: string[];
+    format?: "markdown" | "text" | undefined;
+}, {
+    urls: string[];
+    format?: "markdown" | "text" | undefined;
+}>;
+/**
+ * A tool that reads the main text of web pages and documents live with the
+ * SpecStream Extract API.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+export declare class SpecStreamExtract extends StructuredTool<typeof inputSchema> {
+    static lc_name(): string;
+    description: string;
+    name: string;
+    schema: z.ZodObject<{
+        urls: z.ZodArray<z.ZodString, "many">;
+        format: z.ZodOptional<z.ZodEnum<["markdown", "text"]>>;
+    }, "strip", z.ZodTypeAny, {
+        urls: string[];
+        format?: "markdown" | "text" | undefined;
+    }, {
+        urls: string[];
+        format?: "markdown" | "text" | undefined;
+    }>;
+    format?: "markdown" | "text";
+    private apiWrapper;
+    constructor(params?: SpecStreamExtractAPIRetrieverFields);
+    _call(input: InferInteropZodOutput<typeof inputSchema>, _runManager?: CallbackManagerForToolRun): Promise<SpecStreamExtractResponse | {
+        error: string;
+    }>;
+}
+export {};

package/dist/cjs/specstream-extract.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecStreamExtract = void 0;
+const v3_1 = require("zod/v3");
+const tools_1 = require("@langchain/core/tools");
+const utils_js_1 = require("./utils.js");
+const inputSchema = v3_1.z.object({
+    urls: v3_1.z
+        .array(v3_1.z.string().min(1))
+        .min(1)
+        .max(20)
+        .describe("1 to 20 http or https URLs of web pages, PDF, Word or Excel files to read."),
+    format: v3_1.z
+        .enum(["markdown", "text"])
+        .optional()
+        .describe('The format of the page text: "markdown" (default) keeps headings, lists and links; "text" is plain text.'),
+});
+/**
+ * A tool that reads the main text of web pages and documents live with the
+ * SpecStream Extract API.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+class SpecStreamExtract extends tools_1.StructuredTool {
+    static lc_name() {
+        return "SpecStreamExtract";
+    }
+    description = "Read the main text, title and published date of up to 20 web pages, PDF, Word or Excel files live with the SpecStream Extract API. Input should be a list of URLs.";
+    name = "specstream_extract";
+    schema = inputSchema;
+    format;
+    apiWrapper;
+    constructor(params = {}) {
+        super(params);
+        if (params.name) {
+            this.name = params.name;
+        }
+        if (params.description) {
+            this.description = params.description;
+        }
+        this.format = params.format;
+        this.apiWrapper =
+            params.apiWrapper ??
+                new utils_js_1.SpecStreamExtractAPIWrapper({
+                    specstreamApiKey: params.specstreamApiKey,
+                    apiBaseUrl: params.apiBaseUrl,
+                });
+    }
+    async _call(input, _runManager) {
+        try {
+            return await this.apiWrapper.rawResults({
+                urls: input.urls,
+                format: this.format ?? input.format,
+            });
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+}
+exports.SpecStreamExtract = SpecStreamExtract;

package/dist/cjs/specstream-search.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod/v3";
+import { CallbackManagerForToolRun } from "@langchain/core/callbacks/manager";
+import { StructuredTool, ToolParams } from "@langchain/core/tools";
+import { InferInteropZodOutput } from "@langchain/core/utils/types";
+import { SpecStreamSearchAPIWrapper, type SpecStreamSearchResponse } from "./utils.js";
+/**
+ * Options for the SpecStreamSearch tool.
+ */
+export type SpecStreamSearchAPIRetrieverFields = ToolParams & {
+    /** The base URL of the SpecStream API. @default "https://api.specstream.ai" */
+    apiBaseUrl?: string;
+    /** The API key. Defaults to the `SPECSTREAM_API_KEY` environment variable. */
+    specstreamApiKey?: string;
+    /** Add the text of the top pages to every search. Takes up to about a second more. @default false */
+    passages?: boolean;
+    /** Replace the tool name. */
+    name?: string;
+    /** Replace the tool description. */
+    description?: string;
+    /** Use a custom API wrapper, for example in tests. */
+    apiWrapper?: SpecStreamSearchAPIWrapper;
+};
+declare const inputSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+/**
+ * A tool that searches the live web with the SpecStream Search API and
+ * returns the answer, matching rows and ranked sources.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+export declare class SpecStreamSearch extends StructuredTool<typeof inputSchema> {
+    static lc_name(): string;
+    description: string;
+    name: string;
+    schema: z.ZodObject<{
+        query: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+    }, {
+        query: string;
+    }>;
+    passages?: boolean;
+    private apiWrapper;
+    constructor(params?: SpecStreamSearchAPIRetrieverFields);
+    _call(input: InferInteropZodOutput<typeof inputSchema>, _runManager?: CallbackManagerForToolRun): Promise<SpecStreamSearchResponse | {
+        error: string;
+    }>;
+}
+export {};

package/dist/cjs/specstream-search.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecStreamSearch = void 0;
+const v3_1 = require("zod/v3");
+const tools_1 = require("@langchain/core/tools");
+const utils_js_1 = require("./utils.js");
+const inputSchema = v3_1.z.object({
+    query: v3_1.z
+        .string()
+        .min(1)
+        .max(2000)
+        .describe("The question or request in everyday words, 1 to 2,000 characters."),
+});
+/**
+ * A tool that searches the live web with the SpecStream Search API and
+ * returns the answer, matching rows and ranked sources.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+class SpecStreamSearch extends tools_1.StructuredTool {
+    static lc_name() {
+        return "SpecStreamSearch";
+    }
+    description = "Search the live web with the SpecStream Search API. Returns the answer with the page it was read from, matching rows with their fields, and ranked sources. Input should be a question or request in everyday words.";
+    name = "specstream_search";
+    schema = inputSchema;
+    passages;
+    apiWrapper;
+    constructor(params = {}) {
+        super(params);
+        if (params.name) {
+            this.name = params.name;
+        }
+        if (params.description) {
+            this.description = params.description;
+        }
+        this.passages = params.passages;
+        this.apiWrapper =
+            params.apiWrapper ??
+                new utils_js_1.SpecStreamSearchAPIWrapper({
+                    specstreamApiKey: params.specstreamApiKey,
+                    apiBaseUrl: params.apiBaseUrl,
+                });
+    }
+    async _call(input, _runManager) {
+        try {
+            return await this.apiWrapper.rawResults({ q: input.query, passages: this.passages });
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+}
+exports.SpecStreamSearch = SpecStreamSearch;

package/dist/cjs/utils.d.ts

@@ -0,0 +1,90 @@
+export declare const SPECSTREAM_BASE_URL = "https://api.specstream.ai";
+export declare const MAX_EXTRACT_URLS = 20;
+export type SpecStreamSearchParams = {
+    /** The question or request in everyday words, 1 to 2,000 characters. */
+    q: string;
+    /** Add the text of the top pages to the reply. */
+    passages?: boolean;
+};
+export type SpecStreamSource = {
+    url: string;
+    title?: string;
+    site?: string;
+    snippet?: string;
+    published?: string;
+    cited?: boolean;
+};
+export type SpecStreamSearchResponse = {
+    id?: string;
+    request_id?: string;
+    kind: "fact" | "list";
+    query?: string;
+    columns?: unknown[];
+    answer: {
+        value: string;
+        page: string;
+        seen_at?: string;
+    } | null;
+    rows: Array<{
+        name?: string;
+        page?: string;
+        snippet?: string;
+        probability?: number;
+        sources?: string[];
+        fields?: Record<string, unknown>;
+    }>;
+    sources: SpecStreamSource[];
+    passages?: Array<{
+        url: string;
+        title?: string;
+        text: string;
+    }>;
+    handoff?: Record<string, unknown>;
+    took_ms?: number;
+    price_usd?: number;
+};
+export type SpecStreamExtractParams = {
+    /** 1 to 20 http or https URLs. */
+    urls: string[];
+    format?: "markdown" | "text";
+};
+export type SpecStreamExtractResult = {
+    url: string;
+    status: "ok" | "blocked" | "not_found" | "empty" | "unsupported" | "invalid_url" | "failed";
+    text?: string;
+    title?: string;
+    published?: string;
+    read_from?: "live" | "site" | "archive";
+    captured_at?: string;
+};
+export type SpecStreamExtractResponse = {
+    results: SpecStreamExtractResult[];
+    request_id?: string;
+    took_ms?: number;
+    price_usd?: number;
+};
+export type SpecStreamAPIWrapperParams = {
+    specstreamApiKey?: string;
+    apiBaseUrl?: string;
+};
+declare abstract class BaseSpecStreamAPIWrapper {
+    protected specstreamApiKey: string;
+    protected apiBaseUrl: string;
+    constructor(params?: SpecStreamAPIWrapperParams);
+    protected call<T>(method: "GET" | "POST", path: string, body?: Record<string, unknown>): Promise<T>;
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Search API
+ * (`GET /v1/web-search`). Primarily used for testing.
+ */
+export declare class SpecStreamSearchAPIWrapper extends BaseSpecStreamAPIWrapper {
+    rawResults(params: SpecStreamSearchParams): Promise<SpecStreamSearchResponse>;
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Extract API
+ * (`POST /v1/extract`). Primarily used for testing.
+ */
+export declare class SpecStreamExtractAPIWrapper extends BaseSpecStreamAPIWrapper {
+    rawResults(params: SpecStreamExtractParams): Promise<SpecStreamExtractResponse>;
+}
+export {};

package/dist/cjs/utils.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecStreamExtractAPIWrapper = exports.SpecStreamSearchAPIWrapper = exports.MAX_EXTRACT_URLS = exports.SPECSTREAM_BASE_URL = void 0;
+const env_1 = require("@langchain/core/utils/env");
+exports.SPECSTREAM_BASE_URL = "https://api.specstream.ai";
+exports.MAX_EXTRACT_URLS = 20;
+class BaseSpecStreamAPIWrapper {
+    specstreamApiKey;
+    apiBaseUrl;
+    constructor(params = {}) {
+        const apiKey = (params.specstreamApiKey ?? (0, env_1.getEnvironmentVariable)("SPECSTREAM_API_KEY") ?? "").trim();
+        if (!apiKey) {
+            throw new Error("No SpecStream API key found. Pass specstreamApiKey or set SPECSTREAM_API_KEY. Create a key under Agents & API in your SpecStream workspace.");
+        }
+        this.specstreamApiKey = apiKey.replace(/^bearer\s+/i, "");
+        this.apiBaseUrl = (params.apiBaseUrl ?? (0, env_1.getEnvironmentVariable)("SPECSTREAM_BASE_URL") ?? exports.SPECSTREAM_BASE_URL).replace(/\/+$/, "");
+    }
+    async call(method, path, body) {
+        const response = await fetch(`${this.apiBaseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.specstreamApiKey}`,
+                Accept: "application/json",
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                "User-Agent": "@specstream/langchain",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let payload = {};
+        try {
+            payload = await response.json();
+        }
+        catch {
+            // A reply that is not JSON is reported by its status below.
+        }
+        if (!response.ok || !payload?.data) {
+            throw new Error(`Error ${response.status}: ${payload?.error?.message ?? "Unknown error"}`);
+        }
+        return payload.data;
+    }
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Search API
+ * (`GET /v1/web-search`). Primarily used for testing.
+ */
+class SpecStreamSearchAPIWrapper extends BaseSpecStreamAPIWrapper {
+    async rawResults(params) {
+        const query = new URLSearchParams({ q: params.q.trim() });
+        if (params.passages) {
+            query.set("passages", "true");
+        }
+        return this.call("GET", `/v1/web-search?${query.toString()}`);
+    }
+}
+exports.SpecStreamSearchAPIWrapper = SpecStreamSearchAPIWrapper;
+/**
+ * A wrapper that encapsulates access to the SpecStream Extract API
+ * (`POST /v1/extract`). Primarily used for testing.
+ */
+class SpecStreamExtractAPIWrapper extends BaseSpecStreamAPIWrapper {
+    async rawResults(params) {
+        const urls = params.urls.map((url) => url.trim()).filter(Boolean).slice(0, exports.MAX_EXTRACT_URLS);
+        return this.call("POST", "/v1/extract", {
+            urls,
+            format: params.format === "text" ? "text" : "markdown",
+        });
+    }
+}
+exports.SpecStreamExtractAPIWrapper = SpecStreamExtractAPIWrapper;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { SpecStreamSearchAPIRetrieverFields } from "./specstream-search.js";
+export { SpecStreamSearch } from "./specstream-search.js";
+export type { SpecStreamExtractAPIRetrieverFields } from "./specstream-extract.js";
+export { SpecStreamExtract } from "./specstream-extract.js";
+export type { SpecStreamAPIWrapperParams, SpecStreamExtractParams, SpecStreamExtractResponse, SpecStreamExtractResult, SpecStreamSearchParams, SpecStreamSearchResponse, SpecStreamSource, } from "./utils.js";
+export { SpecStreamSearchAPIWrapper, SpecStreamExtractAPIWrapper } from "./utils.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SpecStreamSearch } from "./specstream-search.js";
+export { SpecStreamExtract } from "./specstream-extract.js";
+export { SpecStreamSearchAPIWrapper, SpecStreamExtractAPIWrapper } from "./utils.js";

package/dist/specstream-extract.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod/v3";
+import { CallbackManagerForToolRun } from "@langchain/core/callbacks/manager";
+import { StructuredTool, ToolParams } from "@langchain/core/tools";
+import { InferInteropZodOutput } from "@langchain/core/utils/types";
+import { SpecStreamExtractAPIWrapper, type SpecStreamExtractResponse } from "./utils.js";
+/**
+ * Options for the SpecStreamExtract tool.
+ */
+export type SpecStreamExtractAPIRetrieverFields = ToolParams & {
+    /** The base URL of the SpecStream API. @default "https://api.specstream.ai" */
+    apiBaseUrl?: string;
+    /** The API key. Defaults to the `SPECSTREAM_API_KEY` environment variable. */
+    specstreamApiKey?: string;
+    /** Output format of the page text. Takes precedence over the call parameter. */
+    format?: "markdown" | "text";
+    /** Replace the tool name. */
+    name?: string;
+    /** Replace the tool description. */
+    description?: string;
+    /** Use a custom API wrapper, for example in tests. */
+    apiWrapper?: SpecStreamExtractAPIWrapper;
+};
+declare const inputSchema: z.ZodObject<{
+    urls: z.ZodArray<z.ZodString, "many">;
+    format: z.ZodOptional<z.ZodEnum<["markdown", "text"]>>;
+}, "strip", z.ZodTypeAny, {
+    urls: string[];
+    format?: "markdown" | "text" | undefined;
+}, {
+    urls: string[];
+    format?: "markdown" | "text" | undefined;
+}>;
+/**
+ * A tool that reads the main text of web pages and documents live with the
+ * SpecStream Extract API.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+export declare class SpecStreamExtract extends StructuredTool<typeof inputSchema> {
+    static lc_name(): string;
+    description: string;
+    name: string;
+    schema: z.ZodObject<{
+        urls: z.ZodArray<z.ZodString, "many">;
+        format: z.ZodOptional<z.ZodEnum<["markdown", "text"]>>;
+    }, "strip", z.ZodTypeAny, {
+        urls: string[];
+        format?: "markdown" | "text" | undefined;
+    }, {
+        urls: string[];
+        format?: "markdown" | "text" | undefined;
+    }>;
+    format?: "markdown" | "text";
+    private apiWrapper;
+    constructor(params?: SpecStreamExtractAPIRetrieverFields);
+    _call(input: InferInteropZodOutput<typeof inputSchema>, _runManager?: CallbackManagerForToolRun): Promise<SpecStreamExtractResponse | {
+        error: string;
+    }>;
+}
+export {};

package/dist/specstream-extract.js

@@ -0,0 +1,58 @@
+import { z } from "zod/v3";
+import { StructuredTool } from "@langchain/core/tools";
+import { SpecStreamExtractAPIWrapper } from "./utils.js";
+const inputSchema = z.object({
+    urls: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(20)
+        .describe("1 to 20 http or https URLs of web pages, PDF, Word or Excel files to read."),
+    format: z
+        .enum(["markdown", "text"])
+        .optional()
+        .describe('The format of the page text: "markdown" (default) keeps headings, lists and links; "text" is plain text.'),
+});
+/**
+ * A tool that reads the main text of web pages and documents live with the
+ * SpecStream Extract API.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+export class SpecStreamExtract extends StructuredTool {
+    static lc_name() {
+        return "SpecStreamExtract";
+    }
+    description = "Read the main text, title and published date of up to 20 web pages, PDF, Word or Excel files live with the SpecStream Extract API. Input should be a list of URLs.";
+    name = "specstream_extract";
+    schema = inputSchema;
+    format;
+    apiWrapper;
+    constructor(params = {}) {
+        super(params);
+        if (params.name) {
+            this.name = params.name;
+        }
+        if (params.description) {
+            this.description = params.description;
+        }
+        this.format = params.format;
+        this.apiWrapper =
+            params.apiWrapper ??
+                new SpecStreamExtractAPIWrapper({
+                    specstreamApiKey: params.specstreamApiKey,
+                    apiBaseUrl: params.apiBaseUrl,
+                });
+    }
+    async _call(input, _runManager) {
+        try {
+            return await this.apiWrapper.rawResults({
+                urls: input.urls,
+                format: this.format ?? input.format,
+            });
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+}

package/dist/specstream-search.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod/v3";
+import { CallbackManagerForToolRun } from "@langchain/core/callbacks/manager";
+import { StructuredTool, ToolParams } from "@langchain/core/tools";
+import { InferInteropZodOutput } from "@langchain/core/utils/types";
+import { SpecStreamSearchAPIWrapper, type SpecStreamSearchResponse } from "./utils.js";
+/**
+ * Options for the SpecStreamSearch tool.
+ */
+export type SpecStreamSearchAPIRetrieverFields = ToolParams & {
+    /** The base URL of the SpecStream API. @default "https://api.specstream.ai" */
+    apiBaseUrl?: string;
+    /** The API key. Defaults to the `SPECSTREAM_API_KEY` environment variable. */
+    specstreamApiKey?: string;
+    /** Add the text of the top pages to every search. Takes up to about a second more. @default false */
+    passages?: boolean;
+    /** Replace the tool name. */
+    name?: string;
+    /** Replace the tool description. */
+    description?: string;
+    /** Use a custom API wrapper, for example in tests. */
+    apiWrapper?: SpecStreamSearchAPIWrapper;
+};
+declare const inputSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+/**
+ * A tool that searches the live web with the SpecStream Search API and
+ * returns the answer, matching rows and ranked sources.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+export declare class SpecStreamSearch extends StructuredTool<typeof inputSchema> {
+    static lc_name(): string;
+    description: string;
+    name: string;
+    schema: z.ZodObject<{
+        query: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+    }, {
+        query: string;
+    }>;
+    passages?: boolean;
+    private apiWrapper;
+    constructor(params?: SpecStreamSearchAPIRetrieverFields);
+    _call(input: InferInteropZodOutput<typeof inputSchema>, _runManager?: CallbackManagerForToolRun): Promise<SpecStreamSearchResponse | {
+        error: string;
+    }>;
+}
+export {};

package/dist/specstream-search.js

@@ -0,0 +1,51 @@
+import { z } from "zod/v3";
+import { StructuredTool } from "@langchain/core/tools";
+import { SpecStreamSearchAPIWrapper } from "./utils.js";
+const inputSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .max(2000)
+        .describe("The question or request in everyday words, 1 to 2,000 characters."),
+});
+/**
+ * A tool that searches the live web with the SpecStream Search API and
+ * returns the answer, matching rows and ranked sources.
+ *
+ * Authentication is handled via an API key, passed at construction or set as
+ * the environment variable `SPECSTREAM_API_KEY`.
+ */
+export class SpecStreamSearch extends StructuredTool {
+    static lc_name() {
+        return "SpecStreamSearch";
+    }
+    description = "Search the live web with the SpecStream Search API. Returns the answer with the page it was read from, matching rows with their fields, and ranked sources. Input should be a question or request in everyday words.";
+    name = "specstream_search";
+    schema = inputSchema;
+    passages;
+    apiWrapper;
+    constructor(params = {}) {
+        super(params);
+        if (params.name) {
+            this.name = params.name;
+        }
+        if (params.description) {
+            this.description = params.description;
+        }
+        this.passages = params.passages;
+        this.apiWrapper =
+            params.apiWrapper ??
+                new SpecStreamSearchAPIWrapper({
+                    specstreamApiKey: params.specstreamApiKey,
+                    apiBaseUrl: params.apiBaseUrl,
+                });
+    }
+    async _call(input, _runManager) {
+        try {
+            return await this.apiWrapper.rawResults({ q: input.query, passages: this.passages });
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,90 @@
+export declare const SPECSTREAM_BASE_URL = "https://api.specstream.ai";
+export declare const MAX_EXTRACT_URLS = 20;
+export type SpecStreamSearchParams = {
+    /** The question or request in everyday words, 1 to 2,000 characters. */
+    q: string;
+    /** Add the text of the top pages to the reply. */
+    passages?: boolean;
+};
+export type SpecStreamSource = {
+    url: string;
+    title?: string;
+    site?: string;
+    snippet?: string;
+    published?: string;
+    cited?: boolean;
+};
+export type SpecStreamSearchResponse = {
+    id?: string;
+    request_id?: string;
+    kind: "fact" | "list";
+    query?: string;
+    columns?: unknown[];
+    answer: {
+        value: string;
+        page: string;
+        seen_at?: string;
+    } | null;
+    rows: Array<{
+        name?: string;
+        page?: string;
+        snippet?: string;
+        probability?: number;
+        sources?: string[];
+        fields?: Record<string, unknown>;
+    }>;
+    sources: SpecStreamSource[];
+    passages?: Array<{
+        url: string;
+        title?: string;
+        text: string;
+    }>;
+    handoff?: Record<string, unknown>;
+    took_ms?: number;
+    price_usd?: number;
+};
+export type SpecStreamExtractParams = {
+    /** 1 to 20 http or https URLs. */
+    urls: string[];
+    format?: "markdown" | "text";
+};
+export type SpecStreamExtractResult = {
+    url: string;
+    status: "ok" | "blocked" | "not_found" | "empty" | "unsupported" | "invalid_url" | "failed";
+    text?: string;
+    title?: string;
+    published?: string;
+    read_from?: "live" | "site" | "archive";
+    captured_at?: string;
+};
+export type SpecStreamExtractResponse = {
+    results: SpecStreamExtractResult[];
+    request_id?: string;
+    took_ms?: number;
+    price_usd?: number;
+};
+export type SpecStreamAPIWrapperParams = {
+    specstreamApiKey?: string;
+    apiBaseUrl?: string;
+};
+declare abstract class BaseSpecStreamAPIWrapper {
+    protected specstreamApiKey: string;
+    protected apiBaseUrl: string;
+    constructor(params?: SpecStreamAPIWrapperParams);
+    protected call<T>(method: "GET" | "POST", path: string, body?: Record<string, unknown>): Promise<T>;
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Search API
+ * (`GET /v1/web-search`). Primarily used for testing.
+ */
+export declare class SpecStreamSearchAPIWrapper extends BaseSpecStreamAPIWrapper {
+    rawResults(params: SpecStreamSearchParams): Promise<SpecStreamSearchResponse>;
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Extract API
+ * (`POST /v1/extract`). Primarily used for testing.
+ */
+export declare class SpecStreamExtractAPIWrapper extends BaseSpecStreamAPIWrapper {
+    rawResults(params: SpecStreamExtractParams): Promise<SpecStreamExtractResponse>;
+}
+export {};

package/dist/utils.js

@@ -0,0 +1,64 @@
+import { getEnvironmentVariable } from "@langchain/core/utils/env";
+export const SPECSTREAM_BASE_URL = "https://api.specstream.ai";
+export const MAX_EXTRACT_URLS = 20;
+class BaseSpecStreamAPIWrapper {
+    specstreamApiKey;
+    apiBaseUrl;
+    constructor(params = {}) {
+        const apiKey = (params.specstreamApiKey ?? getEnvironmentVariable("SPECSTREAM_API_KEY") ?? "").trim();
+        if (!apiKey) {
+            throw new Error("No SpecStream API key found. Pass specstreamApiKey or set SPECSTREAM_API_KEY. Create a key under Agents & API in your SpecStream workspace.");
+        }
+        this.specstreamApiKey = apiKey.replace(/^bearer\s+/i, "");
+        this.apiBaseUrl = (params.apiBaseUrl ?? getEnvironmentVariable("SPECSTREAM_BASE_URL") ?? SPECSTREAM_BASE_URL).replace(/\/+$/, "");
+    }
+    async call(method, path, body) {
+        const response = await fetch(`${this.apiBaseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.specstreamApiKey}`,
+                Accept: "application/json",
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                "User-Agent": "@specstream/langchain",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let payload = {};
+        try {
+            payload = await response.json();
+        }
+        catch {
+            // A reply that is not JSON is reported by its status below.
+        }
+        if (!response.ok || !payload?.data) {
+            throw new Error(`Error ${response.status}: ${payload?.error?.message ?? "Unknown error"}`);
+        }
+        return payload.data;
+    }
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Search API
+ * (`GET /v1/web-search`). Primarily used for testing.
+ */
+export class SpecStreamSearchAPIWrapper extends BaseSpecStreamAPIWrapper {
+    async rawResults(params) {
+        const query = new URLSearchParams({ q: params.q.trim() });
+        if (params.passages) {
+            query.set("passages", "true");
+        }
+        return this.call("GET", `/v1/web-search?${query.toString()}`);
+    }
+}
+/**
+ * A wrapper that encapsulates access to the SpecStream Extract API
+ * (`POST /v1/extract`). Primarily used for testing.
+ */
+export class SpecStreamExtractAPIWrapper extends BaseSpecStreamAPIWrapper {
+    async rawResults(params) {
+        const urls = params.urls.map((url) => url.trim()).filter(Boolean).slice(0, MAX_EXTRACT_URLS);
+        return this.call("POST", "/v1/extract", {
+            urls,
+            format: params.format === "text" ? "text" : "markdown",
+        });
+    }
+}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@specstream/langchain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The live web data engine for LangChain.js: Search API ($5 per 1,000 searches), Extract API ($0.80 per 1,000 pages) and Deep Search.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}\\n')\"",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.25.76 || ^4"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "langchain",
+    "langchainjs",
+    "specstream",
+    "search-api",
+    "extract-api",
+    "web-search",
+    "web-data",
+    "live-web",
+    "agents"
+  ],
+  "author": {
+    "name": "SpecStream",
+    "email": "support@specstream.ai",
+    "url": "https://specstream.ai"
+  },
+  "license": "MIT",
+  "homepage": "https://specstream.ai/docs/langchain",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/specstream/specstream-tools.git",
+    "directory": "packages/langchain-js"
+  },
+  "bugs": {
+    "url": "https://github.com/specstream/specstream-tools/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}