crw-sdk 0.15.0

package/README.md

@@ -0,0 +1,78 @@
+# crw-sdk
+
+TypeScript/JavaScript SDK for [CRW](https://github.com/us/crw) — the fast,
+Firecrawl-compatible web scraper. Scrape, crawl, map, search, parse, and extract
+any website from Node.
+
+Zero runtime dependencies (Node 18+ `fetch`). Dual ESM + CommonJS.
+
+## Install
+
+```bash
+npm install crw-sdk
+```
+
+## Quick start — Cloud (default)
+
+CRW is **cloud-first**. [Sign up for 500 free credits](https://fastcrw.com/dashboard)
+— no payment, no monthly reset (GitHub/Google, ~10s) — then set `CRW_API_KEY`:
+
+```ts
+import { CrwClient } from "crw-sdk";
+
+const crw = new CrwClient(); // reads CRW_API_KEY from the env
+const res = await crw.scrape("https://example.com", { formats: ["markdown"] });
+console.log(res.markdown);
+```
+
+```ts
+// ...or pass the key explicitly
+const crw = new CrwClient({ apiKey: "fc-..." });
+```
+
+## Self-hosting
+
+```ts
+// A self-hosted server:
+const crw = new CrwClient({ apiUrl: "http://localhost:3000" });
+```
+
+```bash
+# Local zero-config engine (no server, no key): set CRW_LOCAL=1.
+# Requires the `crw-mcp` binary on PATH (or set CRW_BINARY).
+CRW_LOCAL=1 node app.js
+```
+
+## Methods
+
+| Method | Description | Mode |
+|---|---|---|
+| `scrape(url, opts?)` | Scrape one URL | both |
+| `crawl(url, opts?)` | Crawl a site (async, polled) | both |
+| `map(url, opts?)` | Discover URLs | both |
+| `search(query, opts?)` | Web search (+ optional scrape) | both¹ |
+| `parseFile(bytes, opts?)` | PDF → markdown / structured JSON | both |
+| `extract({urls, schema?})` | Structured LLM extraction | HTTP |
+| `batchScrape(urls, opts?)` | Scrape many URLs (async) | HTTP |
+| `capabilities()` | Feature-detect the engine | HTTP |
+| `changeTrackingDiff(cur, prev?)` | Diff vs a prior snapshot | HTTP |
+| `close()` | Shut down the local subprocess | — |
+
+¹ Local search needs a SearXNG URL configured on the engine.
+
+```ts
+// Structured extraction:
+const data = await crw.extract({
+  urls: ["https://example.com"],
+  schema: { type: "object", properties: { title: { type: "string" } } },
+});
+
+// Parse a PDF:
+import { readFileSync } from "node:fs";
+const doc = await crw.parseFile(readFileSync("invoice.pdf"), { formats: ["markdown"] });
+```
+
+## Parity
+
+This SDK mirrors the Python [`crw`](https://pypi.org/project/crw/) client method-for-method,
+and both are conformance-tested against the engine's OpenAPI spec.

package/dist/cjs/client.js

@@ -0,0 +1,315 @@
+"use strict";
+/** CRW client — cloud (default), self-hosted HTTP, or local subprocess mode. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrwClient = exports.DOCS_URL = exports.DASHBOARD_URL = exports.CLOUD_API_URL = void 0;
+const errors_js_1 = require("./errors.js");
+const local_js_1 = require("./local.js");
+// CRW is cloud-first: with no explicit apiUrl and no CRW_LOCAL opt-in, the client
+// talks to the managed cloud. Mirrors the Python SDK + CLI onboarding.
+exports.CLOUD_API_URL = "https://api.fastcrw.com";
+exports.DASHBOARD_URL = "https://fastcrw.com/dashboard";
+exports.DOCS_URL = "https://us.github.io/crw";
+const SIGNUP_NUDGE = `No CRW API key found. CRW uses the managed cloud (${exports.CLOUD_API_URL}) by default.\n` +
+    `  -> Sign up at ${exports.DASHBOARD_URL} for 500 free credits — no payment, no monthly ` +
+    `reset (GitHub/Google, ~10s) — then set CRW_API_KEY (or pass apiKey).\n` +
+    `  -> Prefer to self-host? Set CRW_LOCAL=1 to run the local engine. Docs: ${exports.DOCS_URL}`;
+function envTruthy(value) {
+    return !!value && !["0", "false", "no", ""].includes(value.trim().toLowerCase());
+}
+function httpOnlyHint(name, reason) {
+    return (`${name}() requires HTTP mode (${reason}). It is not available with CRW_LOCAL=1. ` +
+        `Use the cloud (set CRW_API_KEY) or pass apiUrl for a self-hosted server.`);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class CrwClient {
+    apiUrl;
+    apiKey;
+    local = null;
+    /**
+     * CRW is cloud-first. With no arguments the client targets the managed cloud
+     * (api.fastcrw.com) and needs an API key — sign up for 500 free credits at
+     * https://fastcrw.com/dashboard. To self-host locally, set `CRW_LOCAL=1`.
+     */
+    constructor(opts = {}) {
+        const env = globalThis.process
+            ?.env ?? {};
+        this.apiKey = opts.apiKey ?? env.CRW_API_KEY;
+        if (envTruthy(env.CRW_LOCAL)) {
+            // Self-host opt-in: zero-config local engine (subprocess), no key.
+            this.apiUrl = null;
+            return;
+        }
+        const explicitUrl = opts.apiUrl ?? env.CRW_API_URL;
+        this.apiUrl = explicitUrl ?? exports.CLOUD_API_URL;
+        // Only the managed-cloud default requires a key; an explicit self-hosted
+        // server may run without auth.
+        if (explicitUrl === undefined && !this.apiKey) {
+            throw new errors_js_1.CrwError(SIGNUP_NUDGE);
+        }
+    }
+    async scrape(url, opts = {}) {
+        const { formats, onlyMainContent = true, includeTags, excludeTags, renderJs, renderer, waitFor, jsonSchema, ...rest } = opts;
+        const args = { url, onlyMainContent };
+        if (formats)
+            args.formats = [...formats];
+        if (includeTags)
+            args.includeTags = includeTags;
+        if (excludeTags)
+            args.excludeTags = excludeTags;
+        if (renderJs !== undefined)
+            args.renderJs = renderJs;
+        if (renderer !== undefined)
+            args.renderer = renderer;
+        if (waitFor !== undefined)
+            args.waitFor = waitFor;
+        if (jsonSchema !== undefined) {
+            args.jsonSchema = jsonSchema;
+            const f = args.formats ?? [];
+            if (!f.includes("json"))
+                args.formats = [...f, "json"];
+        }
+        Object.assign(args, rest);
+        if (this.apiUrl)
+            return this.httpPost("/v1/scrape", args);
+        return this.localTransport().toolCall("crw_scrape", args);
+    }
+    async crawl(url, opts = {}) {
+        const { maxDepth = 2, maxPages = 10, pollInterval = 2, timeout = 300, ...rest } = opts;
+        const args = { url, maxDepth, maxPages, ...rest };
+        if (this.apiUrl)
+            return this.httpCrawl(args, pollInterval, timeout);
+        const result = await this.localTransport().toolCall("crw_crawl", args);
+        const jobId = result.id;
+        if (!jobId)
+            throw new errors_js_1.CrwError(`Crawl did not return job ID: ${JSON.stringify(result)}`);
+        return this.pollLocalCrawl(jobId, pollInterval, timeout);
+    }
+    async map(url, opts = {}) {
+        const { maxDepth = 2, useSitemap = true, ...rest } = opts;
+        const args = { url, maxDepth, useSitemap, ...rest };
+        if (this.apiUrl) {
+            const data = await this.httpPost("/v1/map", args);
+            return data.links ?? [];
+        }
+        const result = await this.localTransport().toolCall("crw_map", args);
+        return result.links ?? [];
+    }
+    /**
+     * Works in both modes; local mode needs a SearXNG URL configured on the engine.
+     */
+    async search(query, opts = {}) {
+        const { limit = 5, lang, tbs, sources, categories, scrapeOptions, ...rest } = opts;
+        const args = { query, limit };
+        if (lang)
+            args.lang = lang;
+        if (tbs)
+            args.tbs = tbs;
+        if (sources)
+            args.sources = sources;
+        if (categories)
+            args.categories = categories;
+        if (scrapeOptions)
+            args.scrapeOptions = scrapeOptions;
+        Object.assign(args, rest);
+        if (this.apiUrl)
+            return this.httpPost("/v1/search", args);
+        return this.localTransport().toolCall("crw_search", args);
+    }
+    /**
+     * Parse a document (PDF) into markdown / structured JSON. Works in both modes.
+     */
+    async parseFile(content, opts = {}) {
+        const { filename = "document.pdf", formats, jsonSchema, parsers, ...rest } = opts;
+        if (this.apiUrl) {
+            const options = {};
+            if (formats)
+                options.formats = [...formats];
+            if (jsonSchema !== undefined)
+                options.jsonSchema = jsonSchema;
+            if (parsers)
+                options.parsers = parsers;
+            Object.assign(options, rest);
+            const form = new FormData();
+            form.append("file", new Blob([content]), filename);
+            if (Object.keys(options).length)
+                form.append("options", JSON.stringify(options));
+            return this.httpMultipart("/v2/parse", form);
+        }
+        const b64 = Buffer.from(content).toString("base64");
+        const args = { filename, contentBase64: b64 };
+        if (formats)
+            args.formats = [...formats];
+        if (jsonSchema !== undefined)
+            args.jsonSchema = jsonSchema;
+        if (parsers)
+            args.parsers = parsers;
+        Object.assign(args, rest);
+        return this.localTransport().toolCall("crw_parse_file", args);
+    }
+    /** Structured LLM extraction across URLs (HTTP mode only). */
+    async extract(opts) {
+        if (!this.apiUrl)
+            throw new errors_js_1.CrwError(httpOnlyHint("extract", "LLM extract job endpoint"));
+        const { urls, prompt, schema, systemPrompt, pollInterval = 2, timeout = 120 } = opts;
+        const body = { urls: [...urls] };
+        if (prompt !== undefined)
+            body.prompt = prompt;
+        if (schema !== undefined)
+            body.schema = schema;
+        if (systemPrompt !== undefined)
+            body.systemPrompt = systemPrompt;
+        const start = await this.httpRequest("POST", "/v2/extract", body, { raw: true });
+        const jobId = start.id;
+        if (!jobId)
+            throw new errors_js_1.CrwError(`extract did not return job ID: ${JSON.stringify(start)}`);
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new errors_js_1.CrwTimeoutError(`Extract ${jobId} timed out after ${timeout}s`);
+            const status = await this.httpRequest("GET", `/v2/extract/${jobId}`, undefined, { raw: true, checkSuccess: false });
+            if (status.status === "completed")
+                return status.data ?? {};
+            if (status.status === "failed")
+                throw new errors_js_1.CrwError(`Extract failed: ${status.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+    /** Scrape many URLs in one async batch job (HTTP mode only). */
+    async batchScrape(urls, opts = {}) {
+        if (!this.apiUrl)
+            throw new errors_js_1.CrwError(httpOnlyHint("batchScrape", "batch job endpoint"));
+        const { formats, pollInterval = 2, timeout = 300, ...rest } = opts;
+        const body = { urls: [...urls], ...rest };
+        if (formats)
+            body.formats = [...formats];
+        const start = await this.httpRequest("POST", "/v2/batch/scrape", body, { raw: true });
+        const jobId = start.id;
+        if (!jobId)
+            throw new errors_js_1.CrwError(`Batch scrape did not return job ID: ${JSON.stringify(start)}`);
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new errors_js_1.CrwTimeoutError(`Batch scrape ${jobId} timed out after ${timeout}s`);
+            const status = await this.httpRequest("GET", `/v2/batch/scrape/${jobId}`, undefined, { raw: true, checkSuccess: false });
+            if (status.status === "completed")
+                return status.data ?? [];
+            if (status.status === "failed")
+                throw new errors_js_1.CrwError(`Batch scrape failed: ${status.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+    /** Feature-detect the engine (HTTP mode only). */
+    async capabilities() {
+        if (!this.apiUrl)
+            throw new errors_js_1.CrwError(httpOnlyHint("capabilities", "server capabilities endpoint"));
+        return this.httpRequest("GET", "/v1/capabilities", undefined, { checkSuccess: false });
+    }
+    /** Diff a page against a prior snapshot (HTTP mode only). */
+    async changeTrackingDiff(current, previous, opts = {}) {
+        if (!this.apiUrl)
+            throw new errors_js_1.CrwError(httpOnlyHint("changeTrackingDiff", "diff endpoint"));
+        const { modes, schema, prompt, ...rest } = opts;
+        const body = { current, modes: modes ? [...modes] : ["gitDiff"] };
+        if (previous !== undefined)
+            body.previous = previous;
+        if (schema !== undefined)
+            body.schema = schema;
+        if (prompt !== undefined)
+            body.prompt = prompt;
+        Object.assign(body, rest);
+        return this.httpPost("/v1/change-tracking/diff", body);
+    }
+    /** Shut down the local subprocess if running. */
+    close() {
+        this.local?.close();
+        this.local = null;
+    }
+    // --- local (subprocess) mode ---
+    localTransport() {
+        if (!this.local)
+            this.local = new local_js_1.LocalTransport();
+        return this.local;
+    }
+    async pollLocalCrawl(jobId, pollInterval, timeout) {
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new errors_js_1.CrwTimeoutError(`Crawl ${jobId} timed out after ${timeout}s`);
+            const result = await this.localTransport().toolCall("crw_check_crawl_status", { id: jobId });
+            if (result.status === "completed")
+                return result.data ?? [];
+            if (result.status === "failed")
+                throw new errors_js_1.CrwError(`Crawl failed: ${result.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+    // --- HTTP mode ---
+    async httpRequest(method, path, body, { raw = false, checkSuccess = true } = {}) {
+        if (this.apiUrl === null)
+            throw new errors_js_1.CrwError("internal: httpRequest in local mode");
+        const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
+        const headers = { "Content-Type": "application/json" };
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        const resp = await fetch(url, { method, headers, body: body ? JSON.stringify(body) : undefined });
+        const result = await this.readJson(resp);
+        if (checkSuccess && result.success === false) {
+            throw new errors_js_1.CrwApiError(result.error ?? "API error", resp.status);
+        }
+        if (raw)
+            return result;
+        return result.data ?? result;
+    }
+    async httpMultipart(path, form) {
+        if (this.apiUrl === null)
+            throw new errors_js_1.CrwError("internal: httpMultipart in local mode");
+        const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
+        const headers = {};
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        const resp = await fetch(url, { method: "POST", headers, body: form });
+        const result = await this.readJson(resp);
+        if (result.success === false)
+            throw new errors_js_1.CrwApiError(result.error ?? "API error", resp.status);
+        return result.data ?? result;
+    }
+    /** Parse the JSON body; surface a non-2xx body's `error` as CrwApiError. */
+    async readJson(resp) {
+        const text = await resp.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            if (!resp.ok)
+                throw new errors_js_1.CrwApiError(`HTTP ${resp.status}: ${resp.statusText}`, resp.status);
+            throw new errors_js_1.CrwApiError(`Invalid JSON response (HTTP ${resp.status})`, resp.status);
+        }
+        if (!resp.ok) {
+            const message = parsed.error ?? parsed.message ?? `HTTP ${resp.status}`;
+            throw new errors_js_1.CrwApiError(message, resp.status);
+        }
+        return parsed;
+    }
+    httpPost(path, body) {
+        return this.httpRequest("POST", path, body);
+    }
+    async httpCrawl(args, pollInterval, timeout) {
+        const result = await this.httpPost("/v1/crawl", args);
+        const jobId = result.id;
+        if (!jobId)
+            throw new errors_js_1.CrwError(`Crawl did not return job ID: ${JSON.stringify(result)}`);
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new errors_js_1.CrwTimeoutError(`Crawl ${jobId} timed out after ${timeout}s`);
+            const status = await this.httpRequest("GET", `/v1/crawl/${jobId}`, undefined, { raw: true });
+            if (status.status === "completed")
+                return status.data ?? [];
+            if (status.status === "failed")
+                throw new errors_js_1.CrwError(`Crawl failed: ${status.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+}
+exports.CrwClient = CrwClient;

package/dist/cjs/errors.js

@@ -0,0 +1,34 @@
+"use strict";
+/** CRW SDK error types. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrwBinaryNotFoundError = exports.CrwTimeoutError = exports.CrwApiError = exports.CrwError = void 0;
+class CrwError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CrwError";
+    }
+}
+exports.CrwError = CrwError;
+class CrwApiError extends CrwError {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "CrwApiError";
+        this.statusCode = statusCode;
+    }
+}
+exports.CrwApiError = CrwApiError;
+class CrwTimeoutError extends CrwError {
+    constructor(message) {
+        super(message);
+        this.name = "CrwTimeoutError";
+    }
+}
+exports.CrwTimeoutError = CrwTimeoutError;
+class CrwBinaryNotFoundError extends CrwError {
+    constructor(message) {
+        super(message);
+        this.name = "CrwBinaryNotFoundError";
+    }
+}
+exports.CrwBinaryNotFoundError = CrwBinaryNotFoundError;

package/dist/cjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrwBinaryNotFoundError = exports.CrwTimeoutError = exports.CrwApiError = exports.CrwError = exports.DOCS_URL = exports.DASHBOARD_URL = exports.CLOUD_API_URL = exports.CrwClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "CrwClient", { enumerable: true, get: function () { return client_js_1.CrwClient; } });
+Object.defineProperty(exports, "CLOUD_API_URL", { enumerable: true, get: function () { return client_js_1.CLOUD_API_URL; } });
+Object.defineProperty(exports, "DASHBOARD_URL", { enumerable: true, get: function () { return client_js_1.DASHBOARD_URL; } });
+Object.defineProperty(exports, "DOCS_URL", { enumerable: true, get: function () { return client_js_1.DOCS_URL; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "CrwError", { enumerable: true, get: function () { return errors_js_1.CrwError; } });
+Object.defineProperty(exports, "CrwApiError", { enumerable: true, get: function () { return errors_js_1.CrwApiError; } });
+Object.defineProperty(exports, "CrwTimeoutError", { enumerable: true, get: function () { return errors_js_1.CrwTimeoutError; } });
+Object.defineProperty(exports, "CrwBinaryNotFoundError", { enumerable: true, get: function () { return errors_js_1.CrwBinaryNotFoundError; } });

package/dist/cjs/local.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Local (CRW_LOCAL) subprocess transport: speaks MCP JSON-RPC to a `crw-mcp`
+ * binary over stdio. Mirrors the Python SDK's subprocess mode.
+ *
+ * v1 finds the binary via the `CRW_BINARY` env var or on `PATH`; auto-download
+ * (as the Python SDK does) is a fast-follow.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalTransport = void 0;
+const node_child_process_1 = require("node:child_process");
+const errors_js_1 = require("./errors.js");
+const BINARY_NAME = process.platform === "win32" ? "crw-mcp.exe" : "crw-mcp";
+class LocalTransport {
+    proc = null;
+    nextId = 0;
+    pending = new Map();
+    buffer = "";
+    resolveBinary() {
+        const env = process.env.CRW_BINARY;
+        if (env)
+            return env;
+        // Rely on PATH resolution by spawning the bare name; if it ENOENTs the
+        // error handler surfaces a clear install hint.
+        return BINARY_NAME;
+    }
+    ensureProcess() {
+        if (this.proc && this.proc.exitCode === null)
+            return this.proc;
+        const bin = this.resolveBinary();
+        const proc = (0, node_child_process_1.spawn)(bin, [], { stdio: ["pipe", "pipe", "ignore"] });
+        proc.on("error", (err) => {
+            const failure = err.code === "ENOENT"
+                ? new errors_js_1.CrwBinaryNotFoundError(`crw-mcp binary not found on PATH. Install it (e.g. \`npm i -g crw-mcp\` or ` +
+                    `\`cargo install crw-mcp\`) or set CRW_BINARY to its path.`)
+                : new errors_js_1.CrwError(`crw-mcp failed to start: ${err.message}`);
+            for (const p of this.pending.values())
+                p.reject(failure);
+            this.pending.clear();
+        });
+        proc.stdout.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => this.onData(chunk));
+        proc.on("exit", () => {
+            for (const p of this.pending.values())
+                p.reject(new errors_js_1.CrwError("crw-mcp process closed unexpectedly"));
+            this.pending.clear();
+        });
+        this.proc = proc;
+        return proc;
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let idx;
+        while ((idx = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const id = msg.id;
+            if (id === undefined || !this.pending.has(id))
+                continue;
+            const p = this.pending.get(id);
+            this.pending.delete(id);
+            if (msg.error) {
+                const err = msg.error;
+                p.reject(new errors_js_1.CrwApiError(err.message ?? JSON.stringify(msg.error)));
+            }
+            else {
+                p.resolve(msg.result ?? {});
+            }
+        }
+    }
+    jsonrpc(method, params) {
+        const proc = this.ensureProcess();
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            proc.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        });
+    }
+    async toolCall(name, args) {
+        const result = await this.jsonrpc("tools/call", { name, arguments: args });
+        const content = result.content?.[0];
+        if (!content)
+            throw new errors_js_1.CrwError(`Empty response from ${name}`);
+        if (result.isError)
+            throw new errors_js_1.CrwApiError(content.text ?? "Unknown error");
+        return JSON.parse(content.text ?? "{}");
+    }
+    close() {
+        if (this.proc && this.proc.exitCode === null) {
+            this.proc.stdin.end();
+            this.proc.kill();
+        }
+        this.proc = null;
+    }
+}
+exports.LocalTransport = LocalTransport;

package/dist/cjs/package.json

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

package/dist/cjs/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Request/response types for the CRW SDK.
+ *
+ * Hand-written against the engine's OpenAPI spec
+ * (crates/crw-server/openapi/openapi.json). Results are returned as the engine's
+ * raw JSON objects, so the result aliases are intentionally permissive.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/client.d.ts

@@ -0,0 +1,45 @@
+/** CRW client — cloud (default), self-hosted HTTP, or local subprocess mode. */
+import type { BatchResult, BatchScrapeOptions, Capabilities, ChangeTrackingOptions, ClientOptions, CrawlOptions, CrawlResult, DiffResult, ExtractOptions, ExtractResult, Json, MapOptions, ParseFileOptions, ParseResult, ScrapeOptions, ScrapeResult, SearchOptions, SearchResult } from "./types.js";
+export declare const CLOUD_API_URL = "https://api.fastcrw.com";
+export declare const DASHBOARD_URL = "https://fastcrw.com/dashboard";
+export declare const DOCS_URL = "https://us.github.io/crw";
+export declare class CrwClient {
+    private apiUrl;
+    private apiKey;
+    private local;
+    /**
+     * CRW is cloud-first. With no arguments the client targets the managed cloud
+     * (api.fastcrw.com) and needs an API key — sign up for 500 free credits at
+     * https://fastcrw.com/dashboard. To self-host locally, set `CRW_LOCAL=1`.
+     */
+    constructor(opts?: ClientOptions);
+    scrape(url: string, opts?: ScrapeOptions): Promise<ScrapeResult>;
+    crawl(url: string, opts?: CrawlOptions): Promise<CrawlResult>;
+    map(url: string, opts?: MapOptions): Promise<string[]>;
+    /**
+     * Works in both modes; local mode needs a SearXNG URL configured on the engine.
+     */
+    search(query: string, opts?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Parse a document (PDF) into markdown / structured JSON. Works in both modes.
+     */
+    parseFile(content: Uint8Array, opts?: ParseFileOptions): Promise<ParseResult>;
+    /** Structured LLM extraction across URLs (HTTP mode only). */
+    extract(opts: ExtractOptions): Promise<ExtractResult>;
+    /** Scrape many URLs in one async batch job (HTTP mode only). */
+    batchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchResult>;
+    /** Feature-detect the engine (HTTP mode only). */
+    capabilities(): Promise<Capabilities>;
+    /** Diff a page against a prior snapshot (HTTP mode only). */
+    changeTrackingDiff(current: Json, previous?: Json, opts?: ChangeTrackingOptions): Promise<DiffResult>;
+    /** Shut down the local subprocess if running. */
+    close(): void;
+    private localTransport;
+    private pollLocalCrawl;
+    private httpRequest;
+    private httpMultipart;
+    /** Parse the JSON body; surface a non-2xx body's `error` as CrwApiError. */
+    private readJson;
+    private httpPost;
+    private httpCrawl;
+}

package/dist/esm/client.js

@@ -0,0 +1,311 @@
+/** CRW client — cloud (default), self-hosted HTTP, or local subprocess mode. */
+import { CrwApiError, CrwError, CrwTimeoutError } from "./errors.js";
+import { LocalTransport } from "./local.js";
+// CRW is cloud-first: with no explicit apiUrl and no CRW_LOCAL opt-in, the client
+// talks to the managed cloud. Mirrors the Python SDK + CLI onboarding.
+export const CLOUD_API_URL = "https://api.fastcrw.com";
+export const DASHBOARD_URL = "https://fastcrw.com/dashboard";
+export const DOCS_URL = "https://us.github.io/crw";
+const SIGNUP_NUDGE = `No CRW API key found. CRW uses the managed cloud (${CLOUD_API_URL}) by default.\n` +
+    `  -> Sign up at ${DASHBOARD_URL} for 500 free credits — no payment, no monthly ` +
+    `reset (GitHub/Google, ~10s) — then set CRW_API_KEY (or pass apiKey).\n` +
+    `  -> Prefer to self-host? Set CRW_LOCAL=1 to run the local engine. Docs: ${DOCS_URL}`;
+function envTruthy(value) {
+    return !!value && !["0", "false", "no", ""].includes(value.trim().toLowerCase());
+}
+function httpOnlyHint(name, reason) {
+    return (`${name}() requires HTTP mode (${reason}). It is not available with CRW_LOCAL=1. ` +
+        `Use the cloud (set CRW_API_KEY) or pass apiUrl for a self-hosted server.`);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class CrwClient {
+    apiUrl;
+    apiKey;
+    local = null;
+    /**
+     * CRW is cloud-first. With no arguments the client targets the managed cloud
+     * (api.fastcrw.com) and needs an API key — sign up for 500 free credits at
+     * https://fastcrw.com/dashboard. To self-host locally, set `CRW_LOCAL=1`.
+     */
+    constructor(opts = {}) {
+        const env = globalThis.process
+            ?.env ?? {};
+        this.apiKey = opts.apiKey ?? env.CRW_API_KEY;
+        if (envTruthy(env.CRW_LOCAL)) {
+            // Self-host opt-in: zero-config local engine (subprocess), no key.
+            this.apiUrl = null;
+            return;
+        }
+        const explicitUrl = opts.apiUrl ?? env.CRW_API_URL;
+        this.apiUrl = explicitUrl ?? CLOUD_API_URL;
+        // Only the managed-cloud default requires a key; an explicit self-hosted
+        // server may run without auth.
+        if (explicitUrl === undefined && !this.apiKey) {
+            throw new CrwError(SIGNUP_NUDGE);
+        }
+    }
+    async scrape(url, opts = {}) {
+        const { formats, onlyMainContent = true, includeTags, excludeTags, renderJs, renderer, waitFor, jsonSchema, ...rest } = opts;
+        const args = { url, onlyMainContent };
+        if (formats)
+            args.formats = [...formats];
+        if (includeTags)
+            args.includeTags = includeTags;
+        if (excludeTags)
+            args.excludeTags = excludeTags;
+        if (renderJs !== undefined)
+            args.renderJs = renderJs;
+        if (renderer !== undefined)
+            args.renderer = renderer;
+        if (waitFor !== undefined)
+            args.waitFor = waitFor;
+        if (jsonSchema !== undefined) {
+            args.jsonSchema = jsonSchema;
+            const f = args.formats ?? [];
+            if (!f.includes("json"))
+                args.formats = [...f, "json"];
+        }
+        Object.assign(args, rest);
+        if (this.apiUrl)
+            return this.httpPost("/v1/scrape", args);
+        return this.localTransport().toolCall("crw_scrape", args);
+    }
+    async crawl(url, opts = {}) {
+        const { maxDepth = 2, maxPages = 10, pollInterval = 2, timeout = 300, ...rest } = opts;
+        const args = { url, maxDepth, maxPages, ...rest };
+        if (this.apiUrl)
+            return this.httpCrawl(args, pollInterval, timeout);
+        const result = await this.localTransport().toolCall("crw_crawl", args);
+        const jobId = result.id;
+        if (!jobId)
+            throw new CrwError(`Crawl did not return job ID: ${JSON.stringify(result)}`);
+        return this.pollLocalCrawl(jobId, pollInterval, timeout);
+    }
+    async map(url, opts = {}) {
+        const { maxDepth = 2, useSitemap = true, ...rest } = opts;
+        const args = { url, maxDepth, useSitemap, ...rest };
+        if (this.apiUrl) {
+            const data = await this.httpPost("/v1/map", args);
+            return data.links ?? [];
+        }
+        const result = await this.localTransport().toolCall("crw_map", args);
+        return result.links ?? [];
+    }
+    /**
+     * Works in both modes; local mode needs a SearXNG URL configured on the engine.
+     */
+    async search(query, opts = {}) {
+        const { limit = 5, lang, tbs, sources, categories, scrapeOptions, ...rest } = opts;
+        const args = { query, limit };
+        if (lang)
+            args.lang = lang;
+        if (tbs)
+            args.tbs = tbs;
+        if (sources)
+            args.sources = sources;
+        if (categories)
+            args.categories = categories;
+        if (scrapeOptions)
+            args.scrapeOptions = scrapeOptions;
+        Object.assign(args, rest);
+        if (this.apiUrl)
+            return this.httpPost("/v1/search", args);
+        return this.localTransport().toolCall("crw_search", args);
+    }
+    /**
+     * Parse a document (PDF) into markdown / structured JSON. Works in both modes.
+     */
+    async parseFile(content, opts = {}) {
+        const { filename = "document.pdf", formats, jsonSchema, parsers, ...rest } = opts;
+        if (this.apiUrl) {
+            const options = {};
+            if (formats)
+                options.formats = [...formats];
+            if (jsonSchema !== undefined)
+                options.jsonSchema = jsonSchema;
+            if (parsers)
+                options.parsers = parsers;
+            Object.assign(options, rest);
+            const form = new FormData();
+            form.append("file", new Blob([content]), filename);
+            if (Object.keys(options).length)
+                form.append("options", JSON.stringify(options));
+            return this.httpMultipart("/v2/parse", form);
+        }
+        const b64 = Buffer.from(content).toString("base64");
+        const args = { filename, contentBase64: b64 };
+        if (formats)
+            args.formats = [...formats];
+        if (jsonSchema !== undefined)
+            args.jsonSchema = jsonSchema;
+        if (parsers)
+            args.parsers = parsers;
+        Object.assign(args, rest);
+        return this.localTransport().toolCall("crw_parse_file", args);
+    }
+    /** Structured LLM extraction across URLs (HTTP mode only). */
+    async extract(opts) {
+        if (!this.apiUrl)
+            throw new CrwError(httpOnlyHint("extract", "LLM extract job endpoint"));
+        const { urls, prompt, schema, systemPrompt, pollInterval = 2, timeout = 120 } = opts;
+        const body = { urls: [...urls] };
+        if (prompt !== undefined)
+            body.prompt = prompt;
+        if (schema !== undefined)
+            body.schema = schema;
+        if (systemPrompt !== undefined)
+            body.systemPrompt = systemPrompt;
+        const start = await this.httpRequest("POST", "/v2/extract", body, { raw: true });
+        const jobId = start.id;
+        if (!jobId)
+            throw new CrwError(`extract did not return job ID: ${JSON.stringify(start)}`);
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new CrwTimeoutError(`Extract ${jobId} timed out after ${timeout}s`);
+            const status = await this.httpRequest("GET", `/v2/extract/${jobId}`, undefined, { raw: true, checkSuccess: false });
+            if (status.status === "completed")
+                return status.data ?? {};
+            if (status.status === "failed")
+                throw new CrwError(`Extract failed: ${status.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+    /** Scrape many URLs in one async batch job (HTTP mode only). */
+    async batchScrape(urls, opts = {}) {
+        if (!this.apiUrl)
+            throw new CrwError(httpOnlyHint("batchScrape", "batch job endpoint"));
+        const { formats, pollInterval = 2, timeout = 300, ...rest } = opts;
+        const body = { urls: [...urls], ...rest };
+        if (formats)
+            body.formats = [...formats];
+        const start = await this.httpRequest("POST", "/v2/batch/scrape", body, { raw: true });
+        const jobId = start.id;
+        if (!jobId)
+            throw new CrwError(`Batch scrape did not return job ID: ${JSON.stringify(start)}`);
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new CrwTimeoutError(`Batch scrape ${jobId} timed out after ${timeout}s`);
+            const status = await this.httpRequest("GET", `/v2/batch/scrape/${jobId}`, undefined, { raw: true, checkSuccess: false });
+            if (status.status === "completed")
+                return status.data ?? [];
+            if (status.status === "failed")
+                throw new CrwError(`Batch scrape failed: ${status.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+    /** Feature-detect the engine (HTTP mode only). */
+    async capabilities() {
+        if (!this.apiUrl)
+            throw new CrwError(httpOnlyHint("capabilities", "server capabilities endpoint"));
+        return this.httpRequest("GET", "/v1/capabilities", undefined, { checkSuccess: false });
+    }
+    /** Diff a page against a prior snapshot (HTTP mode only). */
+    async changeTrackingDiff(current, previous, opts = {}) {
+        if (!this.apiUrl)
+            throw new CrwError(httpOnlyHint("changeTrackingDiff", "diff endpoint"));
+        const { modes, schema, prompt, ...rest } = opts;
+        const body = { current, modes: modes ? [...modes] : ["gitDiff"] };
+        if (previous !== undefined)
+            body.previous = previous;
+        if (schema !== undefined)
+            body.schema = schema;
+        if (prompt !== undefined)
+            body.prompt = prompt;
+        Object.assign(body, rest);
+        return this.httpPost("/v1/change-tracking/diff", body);
+    }
+    /** Shut down the local subprocess if running. */
+    close() {
+        this.local?.close();
+        this.local = null;
+    }
+    // --- local (subprocess) mode ---
+    localTransport() {
+        if (!this.local)
+            this.local = new LocalTransport();
+        return this.local;
+    }
+    async pollLocalCrawl(jobId, pollInterval, timeout) {
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new CrwTimeoutError(`Crawl ${jobId} timed out after ${timeout}s`);
+            const result = await this.localTransport().toolCall("crw_check_crawl_status", { id: jobId });
+            if (result.status === "completed")
+                return result.data ?? [];
+            if (result.status === "failed")
+                throw new CrwError(`Crawl failed: ${result.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+    // --- HTTP mode ---
+    async httpRequest(method, path, body, { raw = false, checkSuccess = true } = {}) {
+        if (this.apiUrl === null)
+            throw new CrwError("internal: httpRequest in local mode");
+        const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
+        const headers = { "Content-Type": "application/json" };
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        const resp = await fetch(url, { method, headers, body: body ? JSON.stringify(body) : undefined });
+        const result = await this.readJson(resp);
+        if (checkSuccess && result.success === false) {
+            throw new CrwApiError(result.error ?? "API error", resp.status);
+        }
+        if (raw)
+            return result;
+        return result.data ?? result;
+    }
+    async httpMultipart(path, form) {
+        if (this.apiUrl === null)
+            throw new CrwError("internal: httpMultipart in local mode");
+        const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
+        const headers = {};
+        if (this.apiKey)
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        const resp = await fetch(url, { method: "POST", headers, body: form });
+        const result = await this.readJson(resp);
+        if (result.success === false)
+            throw new CrwApiError(result.error ?? "API error", resp.status);
+        return result.data ?? result;
+    }
+    /** Parse the JSON body; surface a non-2xx body's `error` as CrwApiError. */
+    async readJson(resp) {
+        const text = await resp.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            if (!resp.ok)
+                throw new CrwApiError(`HTTP ${resp.status}: ${resp.statusText}`, resp.status);
+            throw new CrwApiError(`Invalid JSON response (HTTP ${resp.status})`, resp.status);
+        }
+        if (!resp.ok) {
+            const message = parsed.error ?? parsed.message ?? `HTTP ${resp.status}`;
+            throw new CrwApiError(message, resp.status);
+        }
+        return parsed;
+    }
+    httpPost(path, body) {
+        return this.httpRequest("POST", path, body);
+    }
+    async httpCrawl(args, pollInterval, timeout) {
+        const result = await this.httpPost("/v1/crawl", args);
+        const jobId = result.id;
+        if (!jobId)
+            throw new CrwError(`Crawl did not return job ID: ${JSON.stringify(result)}`);
+        const deadline = Date.now() + timeout * 1000;
+        for (;;) {
+            if (Date.now() > deadline)
+                throw new CrwTimeoutError(`Crawl ${jobId} timed out after ${timeout}s`);
+            const status = await this.httpRequest("GET", `/v1/crawl/${jobId}`, undefined, { raw: true });
+            if (status.status === "completed")
+                return status.data ?? [];
+            if (status.status === "failed")
+                throw new CrwError(`Crawl failed: ${status.error ?? "unknown"}`);
+            await sleep(pollInterval * 1000);
+        }
+    }
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,14 @@
+/** CRW SDK error types. */
+export declare class CrwError extends Error {
+    constructor(message: string);
+}
+export declare class CrwApiError extends CrwError {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+export declare class CrwTimeoutError extends CrwError {
+    constructor(message: string);
+}
+export declare class CrwBinaryNotFoundError extends CrwError {
+    constructor(message: string);
+}

package/dist/esm/errors.js

@@ -0,0 +1,27 @@
+/** CRW SDK error types. */
+export class CrwError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CrwError";
+    }
+}
+export class CrwApiError extends CrwError {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "CrwApiError";
+        this.statusCode = statusCode;
+    }
+}
+export class CrwTimeoutError extends CrwError {
+    constructor(message) {
+        super(message);
+        this.name = "CrwTimeoutError";
+    }
+}
+export class CrwBinaryNotFoundError extends CrwError {
+    constructor(message) {
+        super(message);
+        this.name = "CrwBinaryNotFoundError";
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { CrwClient, CLOUD_API_URL, DASHBOARD_URL, DOCS_URL } from "./client.js";
+export { CrwError, CrwApiError, CrwTimeoutError, CrwBinaryNotFoundError } from "./errors.js";
+export type { ClientOptions, ScrapeOptions, CrawlOptions, MapOptions, SearchOptions, ParseFileOptions, ExtractOptions, BatchScrapeOptions, ChangeTrackingOptions, ScrapeResult, CrawlResult, SearchResult, ParseResult, ExtractResult, BatchResult, Capabilities, DiffResult, Json, } from "./types.js";

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { CrwClient, CLOUD_API_URL, DASHBOARD_URL, DOCS_URL } from "./client.js";
+export { CrwError, CrwApiError, CrwTimeoutError, CrwBinaryNotFoundError } from "./errors.js";

package/dist/esm/local.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Local (CRW_LOCAL) subprocess transport: speaks MCP JSON-RPC to a `crw-mcp`
+ * binary over stdio. Mirrors the Python SDK's subprocess mode.
+ *
+ * v1 finds the binary via the `CRW_BINARY` env var or on `PATH`; auto-download
+ * (as the Python SDK does) is a fast-follow.
+ */
+import type { Json } from "./types.js";
+export declare class LocalTransport {
+    private proc;
+    private nextId;
+    private pending;
+    private buffer;
+    private resolveBinary;
+    private ensureProcess;
+    private onData;
+    private jsonrpc;
+    toolCall(name: string, args: Json): Promise<Json>;
+    close(): void;
+}

package/dist/esm/local.js

@@ -0,0 +1,101 @@
+/**
+ * Local (CRW_LOCAL) subprocess transport: speaks MCP JSON-RPC to a `crw-mcp`
+ * binary over stdio. Mirrors the Python SDK's subprocess mode.
+ *
+ * v1 finds the binary via the `CRW_BINARY` env var or on `PATH`; auto-download
+ * (as the Python SDK does) is a fast-follow.
+ */
+import { spawn } from "node:child_process";
+import { CrwApiError, CrwBinaryNotFoundError, CrwError } from "./errors.js";
+const BINARY_NAME = process.platform === "win32" ? "crw-mcp.exe" : "crw-mcp";
+export class LocalTransport {
+    proc = null;
+    nextId = 0;
+    pending = new Map();
+    buffer = "";
+    resolveBinary() {
+        const env = process.env.CRW_BINARY;
+        if (env)
+            return env;
+        // Rely on PATH resolution by spawning the bare name; if it ENOENTs the
+        // error handler surfaces a clear install hint.
+        return BINARY_NAME;
+    }
+    ensureProcess() {
+        if (this.proc && this.proc.exitCode === null)
+            return this.proc;
+        const bin = this.resolveBinary();
+        const proc = spawn(bin, [], { stdio: ["pipe", "pipe", "ignore"] });
+        proc.on("error", (err) => {
+            const failure = err.code === "ENOENT"
+                ? new CrwBinaryNotFoundError(`crw-mcp binary not found on PATH. Install it (e.g. \`npm i -g crw-mcp\` or ` +
+                    `\`cargo install crw-mcp\`) or set CRW_BINARY to its path.`)
+                : new CrwError(`crw-mcp failed to start: ${err.message}`);
+            for (const p of this.pending.values())
+                p.reject(failure);
+            this.pending.clear();
+        });
+        proc.stdout.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => this.onData(chunk));
+        proc.on("exit", () => {
+            for (const p of this.pending.values())
+                p.reject(new CrwError("crw-mcp process closed unexpectedly"));
+            this.pending.clear();
+        });
+        this.proc = proc;
+        return proc;
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let idx;
+        while ((idx = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const id = msg.id;
+            if (id === undefined || !this.pending.has(id))
+                continue;
+            const p = this.pending.get(id);
+            this.pending.delete(id);
+            if (msg.error) {
+                const err = msg.error;
+                p.reject(new CrwApiError(err.message ?? JSON.stringify(msg.error)));
+            }
+            else {
+                p.resolve(msg.result ?? {});
+            }
+        }
+    }
+    jsonrpc(method, params) {
+        const proc = this.ensureProcess();
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            proc.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+        });
+    }
+    async toolCall(name, args) {
+        const result = await this.jsonrpc("tools/call", { name, arguments: args });
+        const content = result.content?.[0];
+        if (!content)
+            throw new CrwError(`Empty response from ${name}`);
+        if (result.isError)
+            throw new CrwApiError(content.text ?? "Unknown error");
+        return JSON.parse(content.text ?? "{}");
+    }
+    close() {
+        if (this.proc && this.proc.exitCode === null) {
+            this.proc.stdin.end();
+            this.proc.kill();
+        }
+        this.proc = null;
+    }
+}

package/dist/esm/package.json

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

package/dist/esm/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Request/response types for the CRW SDK.
+ *
+ * Hand-written against the engine's OpenAPI spec
+ * (crates/crw-server/openapi/openapi.json). Results are returned as the engine's
+ * raw JSON objects, so the result aliases are intentionally permissive.
+ */
+export type Json = Record<string, unknown>;
+export interface ClientOptions {
+    /** Explicit server URL (self-hosted). Defaults to the managed cloud. */
+    apiUrl?: string;
+    /** API key for the cloud or an authenticated self-hosted server. */
+    apiKey?: string;
+}
+export interface ScrapeOptions {
+    formats?: string[];
+    onlyMainContent?: boolean;
+    includeTags?: string[];
+    excludeTags?: string[];
+    /** Force the JS renderer on/off (engine `renderJs`). */
+    renderJs?: boolean;
+    /** Pin a renderer tier (engine `renderer`). */
+    renderer?: string;
+    /** Milliseconds to wait after load before extracting (`waitFor`). */
+    waitFor?: number;
+    /** JSON Schema for structured LLM extraction (auto-adds the `json` format). */
+    jsonSchema?: Json;
+    /** Any other engine scrape option, passed through verbatim. */
+    [key: string]: unknown;
+}
+export interface CrawlOptions {
+    maxDepth?: number;
+    maxPages?: number;
+    pollInterval?: number;
+    timeout?: number;
+    [key: string]: unknown;
+}
+export interface MapOptions {
+    maxDepth?: number;
+    useSitemap?: boolean;
+    [key: string]: unknown;
+}
+export interface SearchOptions {
+    limit?: number;
+    lang?: string;
+    tbs?: string;
+    sources?: string[];
+    categories?: string[];
+    scrapeOptions?: Json;
+    [key: string]: unknown;
+}
+export interface ParseFileOptions {
+    filename?: string;
+    formats?: string[];
+    jsonSchema?: Json;
+    parsers?: string[];
+    [key: string]: unknown;
+}
+export interface ExtractOptions {
+    urls: string[];
+    prompt?: string;
+    schema?: Json;
+    systemPrompt?: string;
+    pollInterval?: number;
+    timeout?: number;
+}
+export interface BatchScrapeOptions {
+    formats?: string[];
+    pollInterval?: number;
+    timeout?: number;
+    [key: string]: unknown;
+}
+export interface ChangeTrackingOptions {
+    modes?: string[];
+    schema?: Json;
+    prompt?: string;
+    [key: string]: unknown;
+}
+export type ScrapeResult = Json;
+export type CrawlResult = Json[];
+export type SearchResult = Json | Json[];
+export type ParseResult = Json;
+export type ExtractResult = Json;
+export type BatchResult = Json[];
+export type Capabilities = Json;
+export type DiffResult = Json;

package/dist/esm/types.js

@@ -0,0 +1,8 @@
+/**
+ * Request/response types for the CRW SDK.
+ *
+ * Hand-written against the engine's OpenAPI spec
+ * (crates/crw-server/openapi/openapi.json). Results are returned as the engine's
+ * raw JSON objects, so the result aliases are intentionally permissive.
+ */
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "crw-sdk",
+  "version": "0.15.0",
+  "description": "TypeScript/JavaScript SDK for CRW — scrape, crawl, map, search, parse, and extract any website",
+  "license": "MIT",
+  "homepage": "https://github.com/us/crw",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/us/crw.git"
+  },
+  "keywords": [
+    "web-scraping",
+    "crawler",
+    "scraper",
+    "ai-agent",
+    "firecrawl",
+    "mcp"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/postbuild.mjs",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test dist-test/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}