@pagesift/node 0.81.5 → 0.90.0

package/README.md

@@ -45,6 +45,10 @@ await scraper.close()
 | `scraper.scrape(url, options?)` | `Promise<Page>` | Rejects with `PagesiftError` |
 | `scraper.scrapeMany(urls, options?)` | `Promise<BatchItem[]>` | Same order as input; one failure only affects its own item |
 | `scraper.scrapeStream(urls, options?)` | async iterable of `BatchItem` | Completion order; leaving the loop cancels pending work |
+| `scraper.crawl(url, options?)` | `CrawlStream`, async iterable of `CrawlItem` | Whole-site crawl, one item per finished page; leaving the loop or `cancel()` stops the crawl |
+| `scraper.map(url, options?)` | `Promise<MapLink[]>` | The site's links: `{ url, title?, description? }` |
+| `scraper.parse(data, filename, options?)` | `Promise<Page>` | Parse a local file (PDF, HTML, Word, Excel, PowerPoint, EPUB, CSV); rejects with `PagesiftError` |
+| `scraper.parseStream(files, options?)` | async iterable of `BatchItem` | `files` are `{ data, filename, contentType?, url? }`; completion order, same concurrency and cancellation as `scrapeStream`; `url` of each item is the file name |
 | `scraper.close()` | `Promise<void>` | Stops browser processes |
 
 `html` is a `string` or UTF-8 bytes (`Uint8Array` / `Buffer`). Don't modify a buffer while a call that uses it is running.
@@ -57,6 +61,20 @@ await scraper.close()
 (title, description, language, `statusCode`, `og*` keys, and `metadata.pagesift`: content hashes, redirect chain, ETag, engine used, timings).
 Each property read copies that one field into JS; fields you never read are never copied. `toJSON()` returns everything as a plain object.
 
+**Crawl, map, parse.** `crawl` options: `limit` (default: the HTTP API's), `maxDepth`, `includePaths` / `excludePaths` (path regexes),
+`crawlEntireDomain`, `allowSubdomains`, `sitemap` (`include` (default) / `skip` / `only`), `query`, `adaptive` (needs `query`),
+`ignoreRobotsTxt` (the crawl and every page), `maxConcurrency`, and per-page `formats`, `onlyMainContent`, `engine`.
+Invalid options throw `PagesiftError` from `crawl()` itself. Results go through a bounded channel whose capacity is the crawl's concurrency:
+when the consumer is slower, the crawl waits instead of dropping pages. A `CrawlItem` is `{ url, page?, error? }` (failed pages look like failed
+`BatchItem`s, without `index`). An error in the crawl itself (for example an invalid path regex) rejects the iteration with an `Error` whose
+message starts with the code (`INVALID_REQUEST: …`). `stream.summary` is `null` until the crawl ends, then `{ stopReason, pages, coverage?, termEvidence }`;
+crawls with `query` get it from the engine, other crawls report `limit_reached`, `exhausted` or `cancelled` from the page counts.
+`stream.total`, `stream.pages` and `stream.errors` are live counters.
+`map` options: `limit`, `search` (links containing more of its terms come first), `sitemap`, `ignoreRobotsTxt`.
+`parse` takes a `Uint8Array` / `Buffer`; the type is detected from the content, then the file name extension and `contentType`.
+`parse` options are the scrape options plus `contentType` and `url` (resolves relative links in HTML, never fetched); unknown types and URL-only options
+(`engine: 'browser'`, `waitFor`, `mobile`, conditional requests) reject with `UNSUPPORTED_OPTION`.
+
 **`BatchItem`.** `{ index, url, page?, error? }`, with exactly one of `page` or `error`.
 `error` is `{ code, message, details?, retryAfter? }`, a plain object rather than an `Error`, so a big batch doesn't collect stack traces.
 

package/index.d.ts

@@ -104,6 +104,31 @@ declare global {
   }
 }
 
+/**
+ * 进行中的整站爬取，每完成一页产出一个 `CrawlItem`（`for await`）。提前 `break` 或 `cancel()` 停止爬取；
+ * 结束后 `summary` 给出停止原因。爬取本身出错（比如路径正则写错）时迭代以 Error 拒绝，
+ * 消息以错误码开头（如 `INVALID_REQUEST: …`）。
+ *
+ * This type implements JavaScript's async iterable protocol.
+ * It can be used with `for await...of` loops.
+ * 
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
+ */
+export declare class CrawlStream {
+  /** 停止爬取：引擎不再调度新页面，之后迭代立即结束，已完成、还没取出的页面也丢弃。 */
+  cancel(): void
+  /** 已经确定要抓的页面数（随着发现新链接增长，不超过 `limit`）。 */
+  get total(): number
+  /** 引擎已经交付的成功页数（含还没取出的）。 */
+  get pages(): number
+  /** 引擎已经交付的失败页数（含还没取出的）。 */
+  get errors(): number
+  /** 爬取结束后的说明；结束前为 null。 */
+  get summary(): CrawlSummary | null
+
+  [globalThis.Symbol.asyncIterator](): globalThis.__NapiRsAsyncGenerator<CrawlStream, CrawlItem, void, undefined>
+}
+
 /** 一页的转换或抓取结果。每次读属性都会新建一个 JS 值，需要多次使用时先存到变量里。 */
 export declare class Page {
   /** 正文的 Markdown；`formats` 里没有 `markdown`、或条件请求命中（`notModified`）时为 null。 */
@@ -131,12 +156,23 @@ export declare class Scraper {
   scrapeMany(urls: Array<string>, options?: BatchOptions | undefined | null): Promise<BatchItem[]>
   /** 抓取一批 URL，按完成顺序逐个产出（`for await`）。提前 `break` 会取消还没完成的抓取。 */
   scrapeStream(urls: Array<string>, options?: BatchOptions | undefined | null): ScrapeStream
+  /** 整站爬取，每完成一页产出一项（`for await`）；提前 `break` 或 `cancel()` 停止爬取。 */
+  crawl(url: string, options?: CrawlOptions | undefined | null): CrawlStream
+  /** 站点的链接列表（sitemap 加页面上的链接）。失败时 Promise 以 `PagesiftError` 拒绝。 */
+  map(url: string, options?: MapOptions | undefined | null): Promise<MapLink[]>
+  /**
+   * 解析一个文件（PDF、HTML、Word、Excel、PowerPoint、EPUB、CSV），结果和 `scrape` 一样。
+   * 类型按内容识别，认不出时再看文件名的扩展名和 `contentType`。失败时 Promise 以 `PagesiftError` 拒绝。
+   */
+  parse(data: Uint8Array, filename: string, options?: ParseOptions | undefined | null): Promise<Page>
+  /** 解析一批文件，按完成顺序逐个产出（`for await`），`url` 是文件名；并发和取消语义同 `scrapeStream`。 */
+  parseStream(files: Array<ParseFile>, options?: BatchOptions | undefined | null): ScrapeStream
   /** 关闭浏览器进程。之后再调用抓取方法会报错。 */
   close(): Promise<void>
 }
 
 /**
- * 按完成顺序产出 `BatchItem` 的异步迭代器。
+ * 按完成顺序产出 `BatchItem` 的异步迭代器（`scrapeStream`、`parseStream`）。
  *
  * This type implements JavaScript's async iterable protocol.
  * It can be used with `for await...of` loops.
@@ -157,10 +193,11 @@ export interface BatchError {
   retryAfter?: number
 }
 
-/** 批量抓取里一个 URL 的结果：`page` 和 `error` 恰好有一个。 */
+/** 批量抓取（或批量解析）里一项的结果：`page` 和 `error` 恰好有一个。 */
 export interface BatchItem {
   /** 在输入数组里的下标。 */
   index: number
+  /** 抓取时是 URL，解析时是文件名。 */
   url: string
   page?: Page
   error?: BatchError
@@ -192,6 +229,8 @@ export interface BatchOptions {
   ifNoneMatch?: string
   /** 条件请求：`If-Modified-Since`（HTTP 日期）。 */
   ifModifiedSince?: string
+  /** 出口代理（http://, https://, socks5://）。 */
+  proxy?: string
 }
 
 /** 把一段 HTML 转成 Markdown，在当前线程上同步执行（会阻塞事件循环，适合脚本和小页面）。 */
@@ -217,6 +256,122 @@ export interface ConvertOptions {
   formats?: Format[]
 }
 
+/** 爬取里一页的结果：`page` 和 `error` 恰好有一个（失败项和 `scrapeMany` 的一样）。 */
+export interface CrawlItem {
+  url: string
+  page?: Page
+  error?: BatchError
+}
+
+/** `Scraper.crawl` 的选项：爬取范围，加上每页的抓取选项（`formats`、`onlyMainContent`、`engine`）。 */
+export interface CrawlOptions {
+  /** 最多抓多少页；不给时和 HTTP 接口的默认值一样。带 `adaptive` 时只是上限。 */
+  limit?: number
+  /** 从起始页算起最多跟几层链接。 */
+  maxDepth?: number
+  /** 只抓路径匹配这些正则的页面。 */
+  includePaths?: Array<string>
+  /** 不抓路径匹配这些正则的页面。 */
+  excludePaths?: Array<string>
+  /** 不限于起始页所在目录，整个主机都爬。 */
+  crawlEntireDomain?: boolean
+  /** 也爬同一站点的子域名。 */
+  allowSubdomains?: boolean
+  /** `include`（默认，sitemap 和页面链接都用）、`skip`（不读 sitemap）、`only`（只抓 sitemap 里的）。 */
+  sitemap?: 'include' | 'skip' | 'only'
+  /** 按和查询的相关性优先爬取。 */
+  query?: string
+  /** 内容覆盖查询后自动停止（需要 `query`）。 */
+  adaptive?: boolean
+  /** 不检查 robots.txt（整个爬取和每一页）。 */
+  ignoreRobotsTxt?: boolean
+  /** 这次爬取同时在抓的页面数上限。 */
+  maxConcurrency?: number
+  /** 每页计算哪些输出，默认 `['markdown']`。 */
+  formats?: Format[]
+  /** 每页只保留正文，默认 true。 */
+  onlyMainContent?: boolean
+  /** `auto`（默认）、`http` 或 `browser`。 */
+  engine?: 'auto' | 'http' | 'browser'
+}
+
+/** 爬取结束后的说明。 */
+export interface CrawlSummary {
+  /**
+   * `limit_reached`、`exhausted`、`cancelled`；带 `query` 时还有 `coverage_reached`、
+   * `saturated`、`no_relevant_pages`。
+   */
+  stopReason: string
+  /** 自适应爬取结束时的覆盖度（0–1）。 */
+  coverage?: number
+  /** 自适应爬取里每个查询词收集到的证据块数。 */
+  termEvidence: Record<string, number>
+  pages: number
+}
+
+/** 站点里的一个链接。 */
+export interface MapLink {
+  url: string
+  title?: string
+  description?: string
+}
+
+/** `Scraper.map` 的选项。 */
+export interface MapOptions {
+  /** 最多返回多少个链接；不给时和 HTTP 接口的默认值一样。 */
+  limit?: number
+  /** 地址里命中搜索词多的链接排在前面，没命中的保留在后面。 */
+  search?: string
+  /** 取值同 `CrawlOptions.sitemap`。 */
+  sitemap?: 'include' | 'skip' | 'only'
+  /** 不检查 robots.txt。 */
+  ignoreRobotsTxt?: boolean
+}
+
+/** `parseStream` 的一个输入文件。 */
+export interface ParseFile {
+  /** 文件内容（`Buffer` 也可以）。 */
+  data: Uint8Array
+  /** 文件名：内容认不出类型时按扩展名判断，也作为结果的 `metadata.sourceURL`。 */
+  filename: string
+  /** 文件的 Content-Type，按内容和扩展名都认不出时再看它。 */
+  contentType?: string
+  /** 页面原地址：HTML 的相对链接按它解析，也作为 `metadata.sourceURL`；不会去抓。 */
+  url?: string
+}
+
+/** `parse` 的选项：`ScrapeOptions` 的字段（浏览器渲染、条件请求等只对网址有意义的选项会被拒绝），加上文件的 Content-Type 和原地址。 */
+export interface ParseOptions {
+  /** 文件的 Content-Type，按内容和扩展名都认不出类型时再看它。 */
+  contentType?: string
+  /** 页面原地址：HTML 的相对链接按它解析，也作为 `metadata.sourceURL`；不会去抓。 */
+  url?: string
+  /** 计算哪些输出，默认 `['markdown']`；只算需要的，越少越快。 */
+  formats?: Format[]
+  /** 只保留正文，去掉导航、页眉页脚、侧边栏，默认 true。 */
+  onlyMainContent?: boolean
+  /** `auto`（默认，正文太少时改用浏览器渲染）、`http` 或 `browser`。 */
+  engine?: 'auto' | 'http' | 'browser'
+  /** 总超时，毫秒，至少 1000。 */
+  timeout?: number
+  /** 浏览器渲染时页面加载后再等待多久，毫秒。 */
+  waitFor?: number
+  /** 额外的请求头。 */
+  headers?: Record<string, string>
+  /** 这一页不检查 robots.txt（只对单页抓取有效）。 */
+  ignoreRobotsTxt?: boolean
+  /** 浏览器渲染时模拟手机。 */
+  mobile?: boolean
+  /** 浏览器渲染时屏蔽广告，默认 true。 */
+  blockAds?: boolean
+  /** 条件请求：`If-None-Match`。 */
+  ifNoneMatch?: string
+  /** 条件请求：`If-Modified-Since`（HTTP 日期）。 */
+  ifModifiedSince?: string
+  /** 出口代理（http://, https://, socks5://）。 */
+  proxy?: string
+}
+
 /** 单页抓取选项。 */
 export interface ScrapeOptions {
   /** 计算哪些输出，默认 `['markdown']`；只算需要的，越少越快。 */
@@ -241,6 +396,8 @@ export interface ScrapeOptions {
   ifNoneMatch?: string
   /** 条件请求：`If-Modified-Since`（HTTP 日期）。 */
   ifModifiedSince?: string
+  /** 出口代理（http://, https://, socks5://）。 */
+  proxy?: string
 }
 
 /** `Scraper` 的构造参数。 */
@@ -249,6 +406,10 @@ export interface ScraperConfig {
   userAgent?: string
   /** 允许抓取内网、回环地址（默认拒绝，防 SSRF；只作用于 HTTP 抓取）。 */
   allowPrivateNetwork?: boolean
+  /** 单独放行的 CIDR 网段（如 10.0.0.0/8, 198.18.0.0/15）。 */
+  allowCidrs?: Array<string>
+  /** 出口代理（http://, https://, socks5://）。 */
+  proxy?: string
   /** 同一主机两次请求之间的最小间隔，毫秒，默认 1000；robots.txt 的 Crawl-delay 优先。 */
   requestIntervalMs?: number
   /** 同一主机同时进行的请求数，默认 2。 */

package/index.js

@@ -778,6 +778,7 @@ function __napiStampBindingTarget(exportsObject, target) {
 // linked import resolves to `undefined`.
 module.exports.__napiBindingTarget = __napiStampBindingTarget(nativeBinding, __napiLoadedBindingTarget)
 module.exports = nativeBinding
+module.exports.CrawlStream = nativeBinding.CrawlStream
 module.exports.Page = nativeBinding.Page
 module.exports.Scraper = nativeBinding.Scraper
 module.exports.ScrapeStream = nativeBinding.ScrapeStream

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagesift/node",
-  "version": "0.81.5",
+  "version": "0.90.0",
   "description": "Turn web pages into clean Markdown for LLMs: a polite, Firecrawl-compatible scraping engine written in Rust.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -51,11 +51,11 @@
     "@napi-rs/cli": "3.10.8"
   },
   "optionalDependencies": {
-    "@pagesift/node-linux-x64-gnu": "0.81.5",
-    "@pagesift/node-linux-arm64-gnu": "0.81.5",
-    "@pagesift/node-darwin-x64": "0.81.5",
-    "@pagesift/node-darwin-arm64": "0.81.5",
-    "@pagesift/node-linux-x64-musl": "0.81.5",
-    "@pagesift/node-win32-x64-msvc": "0.81.5"
+    "@pagesift/node-linux-x64-gnu": "0.90.0",
+    "@pagesift/node-linux-arm64-gnu": "0.90.0",
+    "@pagesift/node-darwin-x64": "0.90.0",
+    "@pagesift/node-darwin-arm64": "0.90.0",
+    "@pagesift/node-linux-x64-musl": "0.90.0",
+    "@pagesift/node-win32-x64-msvc": "0.90.0"
   }
 }