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 +4 -4
- package/dist/{chunk-7KWNHI4H.js → chunk-5D4KXCYO.js} +4 -4
- package/dist/index.cjs +152 -4
- package/dist/index.d.cts +262 -2
- package/dist/index.d.ts +262 -2
- package/dist/index.js +149 -2
- package/dist/{package-KBCQFPRT.js → package-HESILIET.js} +1 -1
- package/package.json +3 -3
- package/pnpm-workspace.yaml +3 -0
- package/src/__tests__/e2e/v1/index.test.ts +15 -15
- package/src/__tests__/unit/v2/research.test.ts +168 -0
- package/src/index.ts +2 -0
- package/src/v2/client.ts +12 -0
- package/src/v2/methods/research.ts +195 -0
- package/src/v2/types.ts +252 -1
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
|
|
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 '
|
|
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 '
|
|
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 '
|
|
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.
|
|
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.
|
|
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: "^
|
|
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
|
|
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.
|
|
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.
|
|
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: "^
|
|
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
|
|
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 };
|