firecrawl 4.38.0 → 4.40.0

package/README.md

@@ -261,8 +261,13 @@ const related = await app.research.similarPapers('pmid:<id>', {
 });
 ```
 
-A companion `app.research.searchGithub` searches indexed GitHub issue/PR history
-and repository readmes.
+> **`app.research.searchGithub` is deprecated.** The research index GitHub
+> endpoint stops responding after 2026-11-03. Use `app.developerSearch`
+> instead: it searches GitHub issues, pull requests and readmes plus curated
+> documentation sources, returns matched passages, and adds filters for repo,
+> language, license and stars. It does not carry over the `scores` breakdown
+> or the `resultType: "web"` fallback results. See
+> [the developer index docs](https://docs.firecrawl.dev/features/developer).
 
 ### Scrape-bound interactive browsing (v2)
 
@@ -381,3 +386,49 @@ The Firecrawl Node SDK is licensed under the MIT License. This means you are fre
 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.
 
 Please note that while this SDK is MIT licensed, it is part of a larger project which may be under different licensing terms. Always refer to the license information in the root directory of the main project for overall licensing details.
+
+### Alexandria
+
+With a matching API deployment, Search returns complete tool contracts in `tools`.
+`domainTools: true` adds domain matches to that same array. Find Tools walks the catalogue
+without executing the tools it returns.
+
+```ts
+const results = await firecrawl.search("podcast conversations about AI agents", {
+  sources: ["web", "alexandria"],
+  domainTools: true,
+  limit: 2,
+});
+console.log(results.tools?.[0].options);
+
+const catalogue = await firecrawl.findTools({ providers: ["particle"], limit: 2 });
+const next = catalogue.items[0]?.next;
+if (next) console.log(await firecrawl.scrape({ alexandria: next }));
+```
+
+Execute a selected contract with `scrape({ alexandria, requestId })`, where `alexandria`
+is one `{ provider, capability, options }` call or an array of up to ten calls:
+
+```ts
+const requestId = crypto.randomUUID();
+const result = await firecrawl.scrape({
+  alexandria: {
+    provider: "particle",
+    capability: "podcasts/episodes/search",
+    options: { semantic_search: "AI agents" },
+  },
+  requestId,
+});
+for (const item of result.alexandria) {
+  if (item.error) console.error(item.error.code, item.error.message);
+  else console.log(item.data);
+}
+```
+
+Check each returned `alexandria` item's `error` before using its `data`. The result and
+execution errors expose `requestId`; reuse it with the identical payload for a retry.
+Automatic retries retain the same ID. Find Tools costs zero credits; provider execution
+uses its published price. A provider whose data terms have not been accepted rejects the
+call with a 403 whose `SdkError` carries `code: "THIRD_PARTY_DATA_TERMS_REQUIRED"` and a
+`requiresAction: { type: "accept_terms", terms, version, url }` pointing at the page where
+an organization admin can accept them.

package/dist/{chunk-KSTNOGOD.js → chunk-OJ4YJQ4J.js}

@@ -12,7 +12,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.38.0",
+      version: "4.40.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.38.0",
+      version: "4.40.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -129,7 +129,8 @@ __export(index_exports, {
   ResearchClient: () => ResearchClient,
   SdkError: () => SdkError,
   Watcher: () => Watcher,
-  default: () => index_default
+  default: () => index_default,
+  parseRequiresAction: () => parseRequiresAction
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -269,18 +270,35 @@ var HttpClient = class {
 };
 
 // src/v2/types.ts
+function parseRequiresAction(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const record = value;
+  if (typeof record.type !== "string") return void 0;
+  const action = { type: record.type };
+  if (typeof record.terms === "string") action.terms = record.terms;
+  if (typeof record.version === "string") action.version = record.version;
+  if (typeof record.url === "string") action.url = record.url;
+  return action;
+}
 var SdkError = class extends Error {
+  requestId;
   status;
   code;
   details;
   jobId;
-  constructor(message, status, code, details, jobId) {
+  /** Present on exchange-mediated scrape failures that already captured credits. */
+  chargeId;
+  /** Present when the API needs an out-of-band step first, such as accepting provider terms. */
+  requiresAction;
+  constructor(message, status, code, details, jobId, chargeId, requiresAction) {
     super(message);
     this.name = "FirecrawlSdkError";
     this.status = status;
     this.code = code;
     this.details = details;
     this.jobId = jobId;
+    this.chargeId = chargeId;
+    this.requiresAction = requiresAction;
   }
 };
 var JobTimeoutError = class extends SdkError {
@@ -532,14 +550,30 @@ function throwForBadResponse(resp, action) {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(msg, status, void 0, body?.details);
+  throw new SdkError(
+    msg,
+    status,
+    body?.code,
+    body?.details,
+    void 0,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction)
+  );
 }
 function normalizeAxiosError(err, action) {
   const status = err.response?.status;
   const body = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = body?.code || err.code;
-  throw new SdkError(message, status, code, body?.details ?? body);
+  throw new SdkError(
+    message,
+    status,
+    code,
+    body?.details ?? body,
+    void 0,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction)
+  );
 }
 function isRetryableError(err) {
   if (err instanceof JobTimeoutError) {
@@ -585,9 +619,10 @@ async function scrape(http, url, options, deps = {}) {
     throw new Error("URL cannot be empty");
   }
   if (options) ensureValidScrapeOptions(options);
-  const { autoResume, ...requestOptions } = options ?? {};
+  const { autoResume, domainTools, ...requestOptions } = options ?? {};
   const payload = { url: url.trim() };
   Object.assign(payload, requestOptions);
+  if (domainTools) payload.domainTools = domainTools;
   const requestTimeout = autoResume === false ? typeof options?.timeout === "number" ? { timeoutMs: options.timeout + 5e3 } : {} : {
     timeoutMs: Math.max(
       typeof options?.timeout === "number" ? options.timeout : 3e5,
@@ -744,6 +779,7 @@ function prepareSearchPayload(req) {
   const payload = {
     query: req.query
   };
+  if (req.domainTools != null) payload.domainTools = req.domainTools;
   if (req.sources) payload.sources = req.sources;
   if (req.categories) payload.categories = req.categories;
   if (req.includeDomains) payload.includeDomains = req.includeDomains;
@@ -751,6 +787,7 @@ function prepareSearchPayload(req) {
   if (req.limit != null) payload.limit = req.limit;
   if (req.tbs != null) payload.tbs = req.tbs;
   if (req.location != null) payload.location = req.location;
+  if (req.country != null) payload.country = req.country;
   if (req.ignoreInvalidURLs != null)
     payload.ignoreInvalidURLs = req.ignoreInvalidURLs;
   if (req.timeout != null) payload.timeout = req.timeout;
@@ -795,10 +832,12 @@ async function search(http, request) {
     }
     const data = res.data.data || {};
     const out = {};
+    if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray(data.web);
     if (data.news) out.news = transformArray(data.news);
     if (data.images)
       out.images = transformArray(data.images);
+    if (data.tools) out.tools = data.tools;
     Object.defineProperty(out, "data", {
       get() {
         const parts = [];
@@ -806,7 +845,9 @@ async function search(http, request) {
         if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
         if (out.images?.length)
           parts.push(`.images (${out.images.length} results)`);
-        const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
+        if (out.tools?.length)
+          parts.push(`.tools (${out.tools.length} results)`);
+        const available = parts.length ? parts.join(", ") : ".web, .news, .images, or .tools";
         throw new Error(
           `SearchData has no '.data'. Results are grouped by source: ${available}`
         );
@@ -821,6 +862,101 @@ async function search(http, request) {
   }
 }
 
+// src/v2/methods/tools.ts
+var ALEXANDRIA_MAX_CALLS = 10;
+function prepareAlexandriaPayload(calls, opts) {
+  if (!Array.isArray(calls) || calls.length === 0) {
+    throw new Error("alexandria requires at least one call");
+  }
+  if (calls.length > ALEXANDRIA_MAX_CALLS) {
+    throw new Error(`alexandria accepts at most ${ALEXANDRIA_MAX_CALLS} calls`);
+  }
+  const alexandria = calls.map((call, index) => {
+    if (!call || typeof call.provider !== "string" || !call.provider.trim()) {
+      throw new Error(`alexandria[${index}].provider cannot be empty`);
+    }
+    if (typeof call.capability !== "string" || !call.capability.trim()) {
+      throw new Error(`alexandria[${index}].capability cannot be empty`);
+    }
+    if (Object.keys(call).some(
+      (key) => !["provider", "capability", "options"].includes(key)
+    ))
+      throw new Error("Unknown alexandria call option");
+    const item = {
+      provider: call.provider.trim(),
+      capability: call.capability.trim()
+    };
+    if (call.options != null) {
+      if (typeof call.options !== "object" || Array.isArray(call.options)) {
+        throw new Error(`alexandria[${index}].options must be an object`);
+      }
+      item.options = call.options;
+    }
+    return item;
+  });
+  if (opts.timeout != null && (!Number.isInteger(opts.timeout) || opts.timeout <= 0)) {
+    throw new Error("timeout must be a positive integer");
+  }
+  const payload = { alexandria };
+  if (opts.timeout != null) payload.timeout = opts.timeout;
+  if (opts.integration && opts.integration.trim())
+    payload.integration = opts.integration.trim();
+  if (opts.origin) payload.origin = opts.origin;
+  return payload;
+}
+async function scrapeAlexandria(http, calls, opts = {}) {
+  const payload = prepareAlexandriaPayload(calls, opts);
+  const requestId = opts.requestId ?? crypto.randomUUID();
+  if (!/^[A-Za-z0-9._:-]{1,128}$/.test(requestId))
+    throw new Error("Invalid requestId");
+  try {
+    const res = await http.post("/v2/scrape", payload, {
+      headers: { "x-request-id": requestId },
+      // Allow response delivery after the API's capped execution deadline.
+      timeoutMs: Math.min(opts.timeout ?? 5e4, 5e4) + 3e4
+    });
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "alexandria");
+    }
+    const data = res.data.data;
+    if (!data || !Array.isArray(data.alexandria) || typeof data.creditsCost !== "number" || !Number.isInteger(data.creditsCost) || data.creditsCost < 0) {
+      throw new SdkError("Invalid alexandria response");
+    }
+    return {
+      scrapeId: res.data.scrape_id ?? "",
+      requestId,
+      alexandria: data.alexandria,
+      creditsCost: data.creditsCost
+    };
+  } catch (err) {
+    try {
+      if (err?.isAxiosError) normalizeAxiosError(err, "alexandria");
+      throw err;
+    } catch (error) {
+      if (error && typeof error === "object")
+        Object.assign(error, { requestId });
+      throw error;
+    }
+  }
+}
+async function findTools(http, options = {}) {
+  const result = await scrapeAlexandria(http, [
+    {
+      provider: "firecrawl",
+      capability: "find-tools",
+      options: { ...options }
+    }
+  ]);
+  const item = result.alexandria[0];
+  if (!item) throw new SdkError("Missing Find Tools result");
+  if (item.error)
+    throw Object.assign(
+      new SdkError(item.error.message, item.error.status, item.error.code),
+      { requestId: result.requestId }
+    );
+  return item.data;
+}
+
 // src/v2/methods/developer.ts
 var ENDPOINT = "/v2/search/developer";
 async function developerSearch(http, query, options = {}) {
@@ -1371,6 +1507,9 @@ function prepareAgentPayload(args) {
     body.threatProtection = args.threatProtection;
   if (args.auditMetadata != null)
     body.auditMetadata = args.auditMetadata;
+  if (args.threadId != null) body.threadId = args.threadId;
+  if (args.mode != null) body.mode = args.mode;
+  if (args.exchange != null) body.exchange = args.exchange;
   return body;
 }
 async function startAgent(http, args) {
@@ -1441,6 +1580,17 @@ async function getAgentSnapshot(http, jobId, snapshotId) {
     throw err;
   }
 }
+async function getAgentThread(http, threadId, options) {
+  try {
+    const query = options?.includeData ? "?includeData=true" : "";
+    const res = await http.get(`/v2/agent/threads/${threadId}${query}`);
+    if (res.status !== 200) throwForBadResponse(res, "agent thread");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent thread");
+    throw err;
+  }
+}
 async function cancelAgent(http, jobId) {
   try {
     const res = await http.delete(`/v2/agent/${jobId}`);
@@ -1681,9 +1831,7 @@ var ResearchClient = class {
     appendParam(params, "query", options.query);
     appendParam(params, "k", options.k);
     try {
-      const res = await this.http.get(
-        withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params)
-      );
+      const res = await this.http.get(withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params));
       if (res.status !== 200) throwForBadResponse(res, "get paper");
       return res.data;
     } catch (err) {
@@ -1709,10 +1857,7 @@ var ResearchClient = class {
     appendParam(params, "anchor", options.anchor);
     try {
       const res = await this.http.get(
-        withQuery(
-          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
-          params
-        )
+        withQuery(`${BASE}/papers/${encodeURIComponent(id)}/similar`, params)
       );
       if (res.status !== 200) throwForBadResponse(res, "find similar papers");
       return res.data;
@@ -1721,7 +1866,16 @@ var ResearchClient = class {
     }
   }
   /**
-   * Search GitHub issue/PR history and repository readmes.
+   * Search the research index GitHub slice: issue/PR history and repository
+   * readmes.
+   *
+   * @deprecated Use `developerSearch()` on the client instead. This
+   * endpoint stops responding after 2026-11-03. The developer index searches
+   * GitHub issues, pull requests and readmes plus curated documentation
+   * sources, returns matched passages, and adds filters for repo, language,
+   * license and stars. It does not carry over the `scores` breakdown or the
+   * `resultType: "web"` fallback results. See
+   * https://docs.firecrawl.dev/features/developer.
    * @param query Search query.
    * @param options Optional `k`.
    */
@@ -2130,7 +2284,28 @@ var FirecrawlClient = class {
     });
   }
   async scrape(url, options) {
-    return scrape(this.http, url, options);
+    if (typeof url === "string") return scrape(this.http, url, options);
+    if (!url || options !== void 0 || Object.keys(url).some(
+      (key) => ![
+        "alexandria",
+        "requestId",
+        "timeout",
+        "integration",
+        "origin"
+      ].includes(key)
+    )) {
+      throw new Error("Provide an alexandria request without URL scrape options");
+    }
+    const { alexandria, ...opts } = url;
+    return scrapeAlexandria(
+      this.http,
+      Array.isArray(alexandria) ? alexandria : [alexandria],
+      opts
+    );
+  }
+  /** Explore the catalogue without executing the tools it returns. */
+  async findTools(options) {
+    return findTools(this.http, options);
   }
   /**
    * Interact with the browser session associated with a scrape job.
@@ -2210,6 +2385,9 @@ var FirecrawlClient = class {
    * Access the v2 research endpoints — Firecrawl's **research paper index**
    * (~43M paper abstracts) plus GitHub history/readmes.
    *
+   * `research.searchGithub()` is deprecated and stops responding after
+   * 2026-11-03. Use `developerSearch()` instead.
+   *
    * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
    * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
    * computer science.
@@ -2469,6 +2647,14 @@ var FirecrawlClient = class {
   async getAgentSnapshot(jobId, snapshotId) {
     return getAgentSnapshot(this.http, jobId, snapshotId);
   }
+  /**
+   * Get a thread and its runs, oldest turn first.
+   * @param threadId Thread id, as returned by startAgent or getAgentStatus.
+   * @param options.includeData Inline each succeeded run's data.
+   */
+  async getAgentThread(threadId, options) {
+    return getAgentThread(this.http, threadId, options);
+  }
   // Browser
   /**
    * Create a new browser session.
@@ -4011,5 +4197,6 @@ var index_default = Firecrawl;
   JobTimeoutError,
   ResearchClient,
   SdkError,
-  Watcher
+  Watcher,
+  parseRequiresAction
 });