firecrawl 4.25.1 → 4.25.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,7 +7,7 @@ The Firecrawl Node SDK is a library that lets you easily search, scrape, and int
7
7
  To install the Firecrawl Node SDK, you can use npm:
8
8
 
9
9
  ```bash
10
- npm install @mendable/firecrawl-js
10
+ npm install firecrawl
11
11
  ```
12
12
 
13
13
  ## Usage
@@ -18,7 +18,7 @@ npm install @mendable/firecrawl-js
18
18
  Here's an example of how to use the SDK with error handling:
19
19
 
20
20
  ```js
21
- import Firecrawl from '@mendable/firecrawl-js';
21
+ import { Firecrawl } from 'firecrawl';
22
22
 
23
23
  const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });
24
24
 
@@ -114,7 +114,7 @@ const status = await app.getCrawlStatus(id);
114
114
  Use `extract` with a prompt and schema. Zod schemas are supported directly.
115
115
 
116
116
  ```js
117
- import Firecrawl from '@mendable/firecrawl-js';
117
+ import { Firecrawl } from 'firecrawl';
118
118
  import { z } from 'zod';
119
119
 
120
120
  const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });
@@ -236,7 +236,7 @@ await watch.start();
236
236
  The feature‑frozen v1 is still available under `app.v1` with the original method names.
237
237
 
238
238
  ```js
239
- import Firecrawl from '@mendable/firecrawl-js';
239
+ import { Firecrawl } from 'firecrawl';
240
240
 
241
241
  const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });
242
242
 
@@ -8,7 +8,7 @@ var require_package = __commonJS({
8
8
  "package.json"(exports, module) {
9
9
  module.exports = {
10
10
  name: "@mendable/firecrawl-js",
11
- version: "4.25.1",
11
+ version: "4.25.3",
12
12
  description: "JavaScript SDK for Firecrawl API",
13
13
  main: "dist/index.js",
14
14
  types: "dist/index.d.ts",
@@ -34,7 +34,7 @@ var require_package = __commonJS({
34
34
  author: "Mendable.ai",
35
35
  license: "MIT",
36
36
  dependencies: {
37
- axios: "1.15.2",
37
+ axios: "1.16.1",
38
38
  firecrawl: "4.16.0",
39
39
  "typescript-event-target": "^1.1.1",
40
40
  zod: "^3.23.8",
@@ -56,7 +56,7 @@ var require_package = __commonJS({
56
56
  "ts-jest": "^29.4.5",
57
57
  tsup: "^8.5.0",
58
58
  typescript: "^5.4.5",
59
- uuid: "^9.0.1"
59
+ uuid: "^14.0.0"
60
60
  },
61
61
  keywords: [
62
62
  "firecrawl",
@@ -78,7 +78,7 @@ var require_package = __commonJS({
78
78
  "picomatch@<4.0.4": ">=4.0.4",
79
79
  handlebars: ">=4.7.9",
80
80
  "brace-expansion": ">=5.0.6",
81
- "axios@<1.15.2": "1.15.2",
81
+ "axios@>=1.0.0 <1.16.0": "1.16.1",
82
82
  "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
83
83
  }
84
84
  }
package/dist/index.cjs CHANGED
@@ -35,7 +35,7 @@ var require_package = __commonJS({
35
35
  "package.json"(exports2, module2) {
36
36
  module2.exports = {
37
37
  name: "@mendable/firecrawl-js",
38
- version: "4.25.1",
38
+ version: "4.25.3",
39
39
  description: "JavaScript SDK for Firecrawl API",
40
40
  main: "dist/index.js",
41
41
  types: "dist/index.d.ts",
@@ -61,7 +61,7 @@ var require_package = __commonJS({
61
61
  author: "Mendable.ai",
62
62
  license: "MIT",
63
63
  dependencies: {
64
- axios: "1.15.2",
64
+ axios: "1.16.1",
65
65
  firecrawl: "4.16.0",
66
66
  "typescript-event-target": "^1.1.1",
67
67
  zod: "^3.23.8",
@@ -83,7 +83,7 @@ var require_package = __commonJS({
83
83
  "ts-jest": "^29.4.5",
84
84
  tsup: "^8.5.0",
85
85
  typescript: "^5.4.5",
86
- uuid: "^9.0.1"
86
+ uuid: "^14.0.0"
87
87
  },
88
88
  keywords: [
89
89
  "firecrawl",
@@ -105,7 +105,7 @@ var require_package = __commonJS({
105
105
  "picomatch@<4.0.4": ">=4.0.4",
106
106
  handlebars: ">=4.7.9",
107
107
  "brace-expansion": ">=5.0.6",
108
- "axios@<1.15.2": "1.15.2",
108
+ "axios@>=1.0.0 <1.16.0": "1.16.1",
109
109
  "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
110
110
  }
111
111
  }
@@ -120,6 +120,7 @@ __export(index_exports, {
120
120
  FirecrawlAppV1: () => FirecrawlApp,
121
121
  FirecrawlClient: () => FirecrawlClient,
122
122
  JobTimeoutError: () => JobTimeoutError,
123
+ ResearchClient: () => ResearchClient,
123
124
  SdkError: () => SdkError,
124
125
  Watcher: () => Watcher,
125
126
  default: () => index_default
@@ -1425,6 +1426,142 @@ async function getTokenUsageHistorical(http, byApiKey) {
1425
1426
  }
1426
1427
  }
1427
1428
 
1429
+ // src/v2/methods/research.ts
1430
+ var BASE = "/v2/research";
1431
+ function appendParam(params, key, value) {
1432
+ if (value == null) return;
1433
+ if (Array.isArray(value)) {
1434
+ for (const v of value) {
1435
+ if (v != null && String(v).length > 0) params.append(key, String(v));
1436
+ }
1437
+ } else {
1438
+ params.append(key, String(value));
1439
+ }
1440
+ }
1441
+ function withQuery(path, params) {
1442
+ const qs = params.toString();
1443
+ return qs ? `${path}?${qs}` : path;
1444
+ }
1445
+ function normalizeResearchError(err, action) {
1446
+ if (err?.isAxiosError) {
1447
+ const status = err.response?.status;
1448
+ const body = err.response?.data;
1449
+ if (body && (body.detail || body.title)) {
1450
+ const message = body.detail || body.title;
1451
+ throw new SdkError(message, status, body.type, body);
1452
+ }
1453
+ throw new SdkError(
1454
+ err.message || `Request failed while trying to ${action}`,
1455
+ status,
1456
+ err.code,
1457
+ body
1458
+ );
1459
+ }
1460
+ throw err;
1461
+ }
1462
+ var ResearchClient = class {
1463
+ constructor(http) {
1464
+ this.http = http;
1465
+ }
1466
+ /**
1467
+ * Search papers by abstract relevance.
1468
+ * @param query Natural-language search query.
1469
+ * @param options Optional filters (k, authors, categories, from, to).
1470
+ */
1471
+ async searchPapers(query, options = {}) {
1472
+ if (!query || !query.trim()) throw new Error("query cannot be empty");
1473
+ if (options.k != null && options.k <= 0)
1474
+ throw new Error("k must be positive");
1475
+ const params = new URLSearchParams();
1476
+ appendParam(params, "query", query);
1477
+ appendParam(params, "k", options.k);
1478
+ appendParam(params, "authors", options.authors);
1479
+ appendParam(params, "categories", options.categories);
1480
+ appendParam(params, "from", options.from);
1481
+ appendParam(params, "to", options.to);
1482
+ try {
1483
+ const res = await this.http.get(
1484
+ withQuery(`${BASE}/papers`, params)
1485
+ );
1486
+ if (res.status !== 200) throwForBadResponse(res, "search papers");
1487
+ return res.data;
1488
+ } catch (err) {
1489
+ return normalizeResearchError(err, "search papers");
1490
+ }
1491
+ }
1492
+ async getPaper(id, options = {}) {
1493
+ if (!id || !id.trim()) throw new Error("id cannot be empty");
1494
+ if (options.k != null && options.query == null)
1495
+ throw new Error("k is only valid together with query");
1496
+ if (options.k != null && options.k <= 0)
1497
+ throw new Error("k must be positive");
1498
+ const params = new URLSearchParams();
1499
+ appendParam(params, "query", options.query);
1500
+ appendParam(params, "k", options.k);
1501
+ try {
1502
+ const res = await this.http.get(
1503
+ withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params)
1504
+ );
1505
+ if (res.status !== 200) throwForBadResponse(res, "get paper");
1506
+ return res.data;
1507
+ } catch (err) {
1508
+ return normalizeResearchError(err, "get paper");
1509
+ }
1510
+ }
1511
+ /**
1512
+ * Find related papers via the citation graph.
1513
+ * @param id Primary seed paper reference.
1514
+ * @param options Required `intent` plus optional mode, k, rerank, anchor.
1515
+ */
1516
+ async similarPapers(id, options) {
1517
+ if (!id || !id.trim()) throw new Error("id cannot be empty");
1518
+ if (!options?.intent || !options.intent.trim())
1519
+ throw new Error("intent cannot be empty");
1520
+ if (options.k != null && options.k <= 0)
1521
+ throw new Error("k must be positive");
1522
+ const params = new URLSearchParams();
1523
+ appendParam(params, "intent", options.intent);
1524
+ appendParam(params, "mode", options.mode);
1525
+ appendParam(params, "k", options.k);
1526
+ if (options.rerank != null) appendParam(params, "rerank", options.rerank);
1527
+ appendParam(params, "anchor", options.anchor);
1528
+ try {
1529
+ const res = await this.http.get(
1530
+ withQuery(
1531
+ `${BASE}/papers/${encodeURIComponent(id)}/similar`,
1532
+ params
1533
+ )
1534
+ );
1535
+ if (res.status !== 200) throwForBadResponse(res, "find similar papers");
1536
+ return res.data;
1537
+ } catch (err) {
1538
+ return normalizeResearchError(err, "find similar papers");
1539
+ }
1540
+ }
1541
+ /**
1542
+ * Search GitHub issue/PR history and repository readmes.
1543
+ * @param query Search query.
1544
+ * @param options Optional `k`.
1545
+ */
1546
+ async searchGithub(query, options = {}) {
1547
+ if (!query || !query.trim()) throw new Error("query cannot be empty");
1548
+ if (options.k != null && options.k <= 0)
1549
+ throw new Error("k must be positive");
1550
+ const params = new URLSearchParams();
1551
+ appendParam(params, "query", query);
1552
+ appendParam(params, "k", options.k);
1553
+ try {
1554
+ const res = await this.http.get(
1555
+ withQuery(`${BASE}/github`, params)
1556
+ );
1557
+ if (res.status !== 200) throwForBadResponse(res, "search github");
1558
+ return res.data;
1559
+ } catch (err) {
1560
+ return normalizeResearchError(err, "search github");
1561
+ }
1562
+ }
1563
+ };
1564
+
1428
1565
  // src/v2/methods/monitor.ts
1429
1566
  function queryString(params) {
1430
1567
  if (!params) return "";
@@ -1790,6 +1927,7 @@ var Watcher = class extends import_events.EventEmitter {
1790
1927
  var zt = require("zod");
1791
1928
  var FirecrawlClient = class {
1792
1929
  http;
1930
+ _research;
1793
1931
  isCloudService(url) {
1794
1932
  return url.includes("api.firecrawl.dev");
1795
1933
  }
@@ -1862,6 +2000,15 @@ var FirecrawlClient = class {
1862
2000
  async search(query, req = {}) {
1863
2001
  return search(this.http, { query, ...req });
1864
2002
  }
2003
+ // Research
2004
+ /**
2005
+ * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
2006
+ * Example: `firecrawl.research.searchPapers("diffusion models")`.
2007
+ */
2008
+ get research() {
2009
+ if (!this._research) this._research = new ResearchClient(this.http);
2010
+ return this._research;
2011
+ }
1865
2012
  // Map
1866
2013
  /**
1867
2014
  * Map a site to discover URLs (sitemap-aware).
@@ -3619,6 +3766,7 @@ var index_default = Firecrawl;
3619
3766
  FirecrawlAppV1,
3620
3767
  FirecrawlClient,
3621
3768
  JobTimeoutError,
3769
+ ResearchClient,
3622
3770
  SdkError,
3623
3771
  Watcher
3624
3772
  });
package/dist/index.d.cts CHANGED
@@ -4,7 +4,7 @@ import { AxiosResponse, AxiosRequestHeaders } from 'axios';
4
4
  import { EventEmitter } from 'events';
5
5
  import { TypedEventTarget } from 'typescript-event-target';
6
6
 
7
- type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes" | "branding" | "audio" | "video";
7
+ type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes" | "branding" | "audio" | "video" | "pii";
8
8
  interface Viewport {
9
9
  width: number;
10
10
  height: number;
@@ -140,6 +140,7 @@ interface ScrapeOptions {
140
140
  minAge?: number;
141
141
  storeInCache?: boolean;
142
142
  lockdown?: boolean;
143
+ redactPII?: boolean | RedactPIIOptions;
143
144
  profile?: {
144
145
  name: string;
145
146
  saveChanges?: boolean;
@@ -147,6 +148,51 @@ interface ScrapeOptions {
147
148
  integration?: string;
148
149
  origin?: string;
149
150
  }
151
+ type RedactPIIEntity = "PERSON" | "EMAIL" | "PHONE" | "LOCATION" | "FINANCIAL" | "SECRET";
152
+ interface RedactPIIOptions {
153
+ /**
154
+ * accurate (default): model-only redaction. Best precision, cleanest output.
155
+ * aggressive: model + Presidio + spaCy. Higher recall at the cost of precision.
156
+ * fast: Presidio only, no model call. Lower F1, ~2x throughput.
157
+ */
158
+ mode?: "accurate" | "aggressive" | "fast";
159
+ /** Restrict redaction to these entity buckets. Unset means all entities. */
160
+ entities?: RedactPIIEntity[];
161
+ /**
162
+ * tag (default): replace spans with `<KIND>` placeholders.
163
+ * mask: replace spans with `*` of equal length.
164
+ * remove: drop span characters entirely.
165
+ */
166
+ replaceStyle?: "tag" | "mask" | "remove";
167
+ }
168
+ type PIISource = "model" | "heuristics" | "unknown";
169
+ interface PIISpan {
170
+ start: number;
171
+ end: number;
172
+ /** Unified entity bucket. Omitted when `kind` doesn't map onto one. */
173
+ entity?: RedactPIIEntity;
174
+ /** Granular recognizer label from fire-privacy. */
175
+ kind: string;
176
+ source: PIISource;
177
+ /** Confidence in [0, 1] when supplied. */
178
+ score?: number;
179
+ }
180
+ /**
181
+ * - ok: redaction completed; redactedMarkdown is the result.
182
+ * - skipped: redaction was not performed; see `reason`.
183
+ * - failed: redaction was attempted but did not produce a usable result.
184
+ */
185
+ type PIIStatus = "ok" | "skipped" | "failed";
186
+ /** Always set when status !== "ok". */
187
+ type PIIReason = "empty_input" | "too_large" | "upstream_skipped" | "service_unavailable" | "timeout" | "error";
188
+ interface PIIBlock {
189
+ status: PIIStatus;
190
+ reason?: PIIReason;
191
+ redactedMarkdown: string | null;
192
+ spans: PIISpan[];
193
+ /** Span count per entity bucket. Only non-zero entries are present. */
194
+ counts: Partial<Record<RedactPIIEntity, number>>;
195
+ }
150
196
  type ParseFileData = Blob | File | Buffer | Uint8Array | ArrayBuffer | string;
151
197
  interface ParseFile {
152
198
  data: ParseFileData;
@@ -364,6 +410,7 @@ interface Document {
364
410
  warning?: string;
365
411
  changeTracking?: Record<string, unknown>;
366
412
  branding?: BrandingProfile;
413
+ pii?: PIIBlock;
367
414
  }
368
415
  interface PaginationConfig {
369
416
  /** When true (default), automatically follow `next` links and aggregate all documents. */
@@ -522,6 +569,24 @@ interface MonitorEmailNotification {
522
569
  recipients?: string[];
523
570
  includeDiffs?: boolean;
524
571
  }
572
+ /**
573
+ * Per-recipient opt-in state for monitor email notifications.
574
+ *
575
+ * External recipients (not members of the team that owns the monitor) must
576
+ * confirm their subscription via a one-time email before they receive any
577
+ * monitor notifications. Team members are auto-confirmed.
578
+ *
579
+ * - `pending` → confirmation email sent, no notifications yet
580
+ * - `confirmed` → notifications enabled
581
+ * - `unsubscribed` → recipient opted out and cannot be re-added without a new
582
+ * confirmation flow
583
+ */
584
+ interface MonitorEmailRecipientSubscription {
585
+ email: string;
586
+ status: "pending" | "confirmed" | "unsubscribed";
587
+ source: "team" | "opt_in" | "legacy";
588
+ confirmationEmailSent?: boolean;
589
+ }
525
590
  interface MonitorNotification {
526
591
  email?: MonitorEmailNotification;
527
592
  }
@@ -585,6 +650,13 @@ interface Monitor {
585
650
  targets: MonitorTarget[];
586
651
  webhook?: MonitorWebhookConfig | null;
587
652
  notification?: MonitorNotification | null;
653
+ /**
654
+ * Present on create/update/get responses. Reflects the opt-in state of every
655
+ * email recipient currently configured on the monitor. Absent when the API
656
+ * has not reconciled recipients (e.g. team-default delivery with no
657
+ * explicit recipients).
658
+ */
659
+ emailRecipientSubscriptions?: MonitorEmailRecipientSubscription[];
588
660
  retentionDays: number;
589
661
  estimatedCreditsPerMonth?: number | null;
590
662
  lastCheckSummary?: MonitorSummary | null;
@@ -846,6 +918,146 @@ interface BrowserListResponse {
846
918
  sessions?: BrowserSession[];
847
919
  error?: string;
848
920
  }
921
+ /**
922
+ * Source identifiers grouped by namespace. Currently only `arxiv` is
923
+ * populated; each value is an array of ids in that namespace.
924
+ */
925
+ type IdMap = Record<string, string[]>;
926
+ /** Per-candidate ranking signals (present on similarity results). */
927
+ interface PaperSignals {
928
+ /** Raw structural strength (co-citation / coupling counts, or seed overlap). */
929
+ structural: number;
930
+ /** Semantic score from the intent abstract search (0 if absent). */
931
+ semantic: number;
932
+ /** Citation-graph PageRank of the candidate. */
933
+ pagerank: number;
934
+ /** Number of distinct seeds connected to this candidate. */
935
+ seed_overlap: number;
936
+ }
937
+ /** A ranked paper. `paper_id` is canonical; arXiv lives in `ids`. */
938
+ interface PaperResult {
939
+ /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
940
+ paper_id: string;
941
+ ids?: IdMap;
942
+ title: string;
943
+ abstract: string;
944
+ /** Final ranking score (post-rerank when enabled). Not normalized. */
945
+ score: number;
946
+ /** Present on similarity results. */
947
+ signals?: PaperSignals;
948
+ }
949
+ interface PaperMetadata {
950
+ paper_id: string;
951
+ ids?: IdMap;
952
+ title: string;
953
+ abstract: string;
954
+ /** Comma-joined author names. Omitted if unknown. */
955
+ authors?: string;
956
+ /** arXiv categories. Omitted if unknown. */
957
+ categories?: string[];
958
+ /** Original creation date string (format varies). Omitted if unknown. */
959
+ created_date?: string;
960
+ /** Last-updated date string. Omitted if unknown. */
961
+ update_date?: string;
962
+ }
963
+ interface Passage {
964
+ /** In-body passage text (may be markdown, including tables). */
965
+ text: string;
966
+ /** Dense similarity score for the passage. */
967
+ score: number;
968
+ }
969
+ interface SearchPapersResponse {
970
+ results: PaperResult[];
971
+ }
972
+ interface PaperMetadataResponse {
973
+ paper: PaperMetadata;
974
+ }
975
+ interface ReadPaperResponse {
976
+ paper: PaperMetadata;
977
+ /** Resolved canonical paper id (empty string if not found via id-key). */
978
+ paper_id: string;
979
+ /** Echo of the read query. */
980
+ query: string;
981
+ /** Top matching in-body passages. */
982
+ passages: Passage[];
983
+ }
984
+ interface SimilarPapersResponse {
985
+ /** Ranked related papers; each carries `signals`. */
986
+ results: PaperResult[];
987
+ /** Number of resolved candidates considered before truncation to `k`. */
988
+ pool_size: number;
989
+ /** True if more resolved candidates existed than were returned. */
990
+ truncated: boolean;
991
+ /** Human-readable note when no results are produced. */
992
+ note?: string | null;
993
+ }
994
+ /** Component scores; each field is present only when that signal contributed. */
995
+ interface GitHubScoreBreakdown {
996
+ rrf?: number;
997
+ semantic?: number;
998
+ lexical?: number;
999
+ fusion?: number;
1000
+ }
1001
+ interface GitHubSearchItem {
1002
+ resultType: "github_history" | "repo_readme";
1003
+ /** `owner/name`. */
1004
+ repo: string;
1005
+ url: string;
1006
+ /** History page type (e.g. `issue`, `pull`). Omitted for readmes. */
1007
+ pageType?: string;
1008
+ /** Issue/PR number. Omitted for readmes. */
1009
+ number?: number;
1010
+ /** Number of matched segments/chunks. Omitted when not applicable. */
1011
+ segmentCount?: number;
1012
+ /** Readme URL (readme results). Omitted otherwise. */
1013
+ readmeUrl?: string;
1014
+ /** Short matched excerpt. */
1015
+ snippet: string;
1016
+ /** Full matched content in markdown. Omitted unless available. */
1017
+ contentMd?: string;
1018
+ scores: GitHubScoreBreakdown;
1019
+ }
1020
+ interface GitHubSearchResponse {
1021
+ results: GitHubSearchItem[];
1022
+ }
1023
+ /** Options for `research.searchPapers`. */
1024
+ interface SearchPapersOptions {
1025
+ /** Number of results to return (1–500, default 40). */
1026
+ k?: number;
1027
+ /** Author substring filter(s); ALL must match (case-insensitive). */
1028
+ authors?: string[];
1029
+ /** arXiv category filter(s) (e.g. `cs.LG`); ALL must match. */
1030
+ categories?: string[];
1031
+ /** Inclusive lower bound on created/updated date (ISO `YYYY-MM-DD`). */
1032
+ from?: string;
1033
+ /** Inclusive upper bound on created/updated date (lexicographic). */
1034
+ to?: string;
1035
+ }
1036
+ /** Options for `research.getPaper`. */
1037
+ interface GetPaperOptions {
1038
+ /** When present, switches to read mode and returns in-body passages. */
1039
+ query?: string;
1040
+ /** Passage count (read mode only; 1–50, default 4). Requires `query`. */
1041
+ k?: number;
1042
+ }
1043
+ /** Options for `research.similarPapers`. */
1044
+ interface SimilarPapersOptions {
1045
+ /** Natural-language intent used to semantically rerank candidates. Required. */
1046
+ intent: string;
1047
+ /** Traversal mode (default `similar`). */
1048
+ mode?: "similar" | "citers" | "references";
1049
+ /** Number of related papers to return (1–500, default 40). */
1050
+ k?: number;
1051
+ /** Apply an additional ZeroEntropy rerank over the fused candidates. */
1052
+ rerank?: boolean;
1053
+ /** Additional seed paper reference(s), same format as `id`. */
1054
+ anchor?: string[];
1055
+ }
1056
+ /** Options for `research.searchGithub`. */
1057
+ interface SearchGithubOptions {
1058
+ /** Number of results to return (1–100, default 20). */
1059
+ k?: number;
1060
+ }
849
1061
 
850
1062
  interface HttpClientOptions {
851
1063
  apiKey: string;
@@ -930,6 +1142,48 @@ declare function listBrowsers(http: HttpClient, args?: {
930
1142
  status?: "active" | "destroyed";
931
1143
  }): Promise<BrowserListResponse>;
932
1144
 
1145
+ /**
1146
+ * Client for the v2 research endpoints (arXiv papers + GitHub history/readmes).
1147
+ * Accessed via `firecrawl.research`.
1148
+ */
1149
+ declare class ResearchClient {
1150
+ private readonly http;
1151
+ constructor(http: HttpClient);
1152
+ /**
1153
+ * Search papers by abstract relevance.
1154
+ * @param query Natural-language search query.
1155
+ * @param options Optional filters (k, authors, categories, from, to).
1156
+ */
1157
+ searchPapers(query: string, options?: SearchPapersOptions): Promise<SearchPapersResponse>;
1158
+ /**
1159
+ * Get paper metadata (detail mode), or read in-body passages (when `query` is
1160
+ * supplied). `k` is only valid together with `query`.
1161
+ * @param id Paper reference: a canonical `paper_id`, an `arxiv:<id>` key, or a
1162
+ * bare arXiv id / URL.
1163
+ * @param options Optional `query` (switches to read mode) and `k`.
1164
+ */
1165
+ getPaper(id: string, options?: {
1166
+ query?: undefined;
1167
+ k?: undefined;
1168
+ }): Promise<PaperMetadataResponse>;
1169
+ getPaper(id: string, options: {
1170
+ query: string;
1171
+ k?: number;
1172
+ }): Promise<ReadPaperResponse>;
1173
+ /**
1174
+ * Find related papers via the citation graph.
1175
+ * @param id Primary seed paper reference.
1176
+ * @param options Required `intent` plus optional mode, k, rerank, anchor.
1177
+ */
1178
+ similarPapers(id: string, options: SimilarPapersOptions): Promise<SimilarPapersResponse>;
1179
+ /**
1180
+ * Search GitHub issue/PR history and repository readmes.
1181
+ * @param query Search query.
1182
+ * @param options Optional `k`.
1183
+ */
1184
+ searchGithub(query: string, options?: SearchGithubOptions): Promise<GitHubSearchResponse>;
1185
+ }
1186
+
933
1187
  type JobKind = "crawl" | "batch";
934
1188
  interface WatcherOptions {
935
1189
  kind?: JobKind;
@@ -985,6 +1239,7 @@ type FirecrawlClientInput = FirecrawlClientOptions | string;
985
1239
  */
986
1240
  declare class FirecrawlClient {
987
1241
  private readonly http;
1242
+ private _research?;
988
1243
  private isCloudService;
989
1244
  /**
990
1245
  * Create a v2 client.
@@ -1045,6 +1300,11 @@ declare class FirecrawlClient {
1045
1300
  * @returns Structured search results.
1046
1301
  */
1047
1302
  search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
1303
+ /**
1304
+ * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
1305
+ * Example: `firecrawl.research.searchPapers("diffusion models")`.
1306
+ */
1307
+ get research(): ResearchClient;
1048
1308
  /**
1049
1309
  * Map a site to discover URLs (sitemap-aware).
1050
1310
  * @param url Root URL to map.
@@ -2208,4 +2468,4 @@ declare class Firecrawl extends FirecrawlClient {
2208
2468
  get v1(): FirecrawlApp;
2209
2469
  }
2210
2470
 
2211
- export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type HighlightsFormat, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorEmailNotification, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorSummary, type MonitorTarget, type MonitorWebhookConfig, type PDFAction, type PaginationConfig, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type PressAction, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };
2471
+ export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorSummary, type MonitorTarget, type MonitorWebhookConfig, type PDFAction, type PIIBlock, type PIIReason, type PIISource, type PIISpan, type PIIStatus, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PressAction, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };