firecrawl 4.25.1 → 4.25.3

package/src/__tests__/unit/v2/research.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "@jest/globals";
+import { ResearchClient } from "../../../v2/methods/research";
+import { SdkError } from "../../../v2/types";
+import type { HttpClient } from "../../../v2/utils/httpClient";
+
+/** Build a ResearchClient whose http.get records the requested URL. */
+function makeClient(
+  responder: (url: string) => { status: number; data: any } = () => ({
+    status: 200,
+    data: {},
+  }),
+) {
+  const calls: string[] = [];
+  const http = {
+    get: async (url: string) => {
+      calls.push(url);
+      return responder(url);
+    },
+  } as unknown as HttpClient;
+  return { client: new ResearchClient(http), calls };
+}
+
+/** Make an axios-like error carrying an RFC 7807 Problem body. */
+function problemError(status: number, body: any) {
+  return { isAxiosError: true, response: { status, data: body }, message: "req failed" };
+}
+
+describe("research.searchPapers", () => {
+  test("builds query string with explode arrays", async () => {
+    const { client, calls } = makeClient(() => ({
+      status: 200,
+      data: { results: [] },
+    }));
+    await client.searchPapers("diffusion models", {
+      k: 10,
+      authors: ["Ho", "Abbeel"],
+      categories: ["cs.LG", "stat.ML"],
+      from: "2020-01-01",
+      to: "2024-12-31",
+    });
+    const url = calls[0];
+    expect(url.startsWith("/v2/research/papers?")).toBe(true);
+    const qs = new URLSearchParams(url.split("?")[1]);
+    expect(qs.get("query")).toBe("diffusion models");
+    expect(qs.get("k")).toBe("10");
+    expect(qs.getAll("authors")).toEqual(["Ho", "Abbeel"]);
+    expect(qs.getAll("categories")).toEqual(["cs.LG", "stat.ML"]);
+    expect(qs.get("from")).toBe("2020-01-01");
+    expect(qs.get("to")).toBe("2024-12-31");
+  });
+
+  test("omits absent options", async () => {
+    const { client, calls } = makeClient(() => ({ status: 200, data: { results: [] } }));
+    await client.searchPapers("q");
+    const qs = new URLSearchParams(calls[0].split("?")[1]);
+    expect([...qs.keys()]).toEqual(["query"]);
+  });
+
+  test("rejects empty query", async () => {
+    const { client } = makeClient();
+    await expect(client.searchPapers("  ")).rejects.toThrow(/query cannot be empty/i);
+  });
+
+  test("rejects non-positive k", async () => {
+    const { client } = makeClient();
+    await expect(client.searchPapers("q", { k: 0 })).rejects.toThrow(/k must be positive/i);
+  });
+
+  test("returns the response body verbatim", async () => {
+    const payload = { results: [{ paper_id: "1", title: "t", abstract: "a", score: 0.1 }] };
+    const { client } = makeClient(() => ({ status: 200, data: payload }));
+    await expect(client.searchPapers("q")).resolves.toEqual(payload);
+  });
+});
+
+describe("research.getPaper", () => {
+  test("detail mode encodes the id and sends no query params", async () => {
+    const { client, calls } = makeClient(() => ({ status: 200, data: { paper: {} } }));
+    await client.getPaper("arxiv:2105.05233");
+    expect(calls[0]).toBe("/v2/research/papers/arxiv%3A2105.05233");
+  });
+
+  test("read mode adds query and k", async () => {
+    const { client, calls } = makeClient(() => ({
+      status: 200,
+      data: { paper: {}, paper_id: "1", query: "q", passages: [] },
+    }));
+    await client.getPaper("123", { query: "noise schedule", k: 4 });
+    const [path, query] = calls[0].split("?");
+    expect(path).toBe("/v2/research/papers/123");
+    const qs = new URLSearchParams(query);
+    expect(qs.get("query")).toBe("noise schedule");
+    expect(qs.get("k")).toBe("4");
+  });
+
+  test("rejects k without query", async () => {
+    const { client } = makeClient();
+    await expect(client.getPaper("123", { k: 4 } as any)).rejects.toThrow(
+      /k is only valid together with query/i,
+    );
+  });
+});
+
+describe("research.similarPapers", () => {
+  test("requires intent", async () => {
+    const { client } = makeClient();
+    await expect(
+      client.similarPapers("123", { intent: "" }),
+    ).rejects.toThrow(/intent cannot be empty/i);
+  });
+
+  test("builds path and query with repeated anchors and rerank", async () => {
+    const { client, calls } = makeClient(() => ({
+      status: 200,
+      data: { results: [], pool_size: 0, truncated: false },
+    }));
+    await client.similarPapers("2105.05233", {
+      intent: "diffusion image synthesis",
+      mode: "citers",
+      k: 20,
+      rerank: false,
+      anchor: ["arxiv:2006.11239", "1503.03585"],
+    });
+    const [path, query] = calls[0].split("?");
+    expect(path).toBe("/v2/research/papers/2105.05233/similar");
+    const qs = new URLSearchParams(query);
+    expect(qs.get("intent")).toBe("diffusion image synthesis");
+    expect(qs.get("mode")).toBe("citers");
+    expect(qs.get("k")).toBe("20");
+    expect(qs.get("rerank")).toBe("false");
+    expect(qs.getAll("anchor")).toEqual(["arxiv:2006.11239", "1503.03585"]);
+  });
+});
+
+describe("research.searchGithub", () => {
+  test("builds query string", async () => {
+    const { client, calls } = makeClient(() => ({ status: 200, data: { results: [] } }));
+    await client.searchGithub("milvus hybrid search", { k: 10 });
+    const qs = new URLSearchParams(calls[0].split("?")[1]);
+    expect(calls[0].startsWith("/v2/research/github?")).toBe(true);
+    expect(qs.get("query")).toBe("milvus hybrid search");
+    expect(qs.get("k")).toBe("10");
+  });
+});
+
+describe("research error mapping", () => {
+  test("maps RFC 7807 Problem detail to SdkError", async () => {
+    const { client } = makeClient(() => {
+      throw problemError(400, {
+        type: "urn:search-pipeline:invalid_request",
+        title: "Bad Request",
+        status: 400,
+        detail: "query is required",
+      });
+    });
+    await expect(client.searchPapers("q")).rejects.toMatchObject({
+      message: "query is required",
+      status: 400,
+    } as Partial<SdkError>);
+  });
+
+  test("falls back to title when detail is absent", async () => {
+    const { client } = makeClient(() => {
+      throw problemError(404, { title: "Not Found", status: 404 });
+    });
+    await expect(client.getPaper("999")).rejects.toThrow(/Not Found/);
+  });
+});

package/src/index.ts

@@ -11,6 +11,8 @@ export { FirecrawlClient } from "./v2/client";
 export * from "./v2/types";
 /** Watcher class and options for crawl/batch job monitoring. */
 export { Watcher, type WatcherOptions } from "./v2/watcher";
+/** Research sub-client (accessed via `firecrawl.research`). */
+export { ResearchClient } from "./v2/methods/research";
 /** Legacy v1 client (feature‑frozen). */
 export { default as FirecrawlAppV1 } from "./v1";
 

package/src/v2/client.ts

@@ -32,6 +32,7 @@ import {
   listBrowsers,
 } from "./methods/browser";
 import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
+import { ResearchClient } from "./methods/research";
 import {
   createMonitor as createMonitorMethod,
   deleteMonitor as deleteMonitorMethod,
@@ -119,6 +120,7 @@ export type FirecrawlClientInput = FirecrawlClientOptions | string;
 
 export class FirecrawlClient {
   private readonly http: HttpClient;
+  private _research?: ResearchClient;
 
   private isCloudService(url: string): boolean {
     return url.includes('api.firecrawl.dev');
@@ -234,6 +236,16 @@ export class FirecrawlClient {
     return search(this.http, { query, ...req });
   }
 
+  // Research
+  /**
+   * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
+   * Example: `firecrawl.research.searchPapers("diffusion models")`.
+   */
+  get research(): ResearchClient {
+    if (!this._research) this._research = new ResearchClient(this.http);
+    return this._research;
+  }
+
   // Map
   /**
    * Map a site to discover URLs (sitemap-aware).

package/src/v2/methods/research.ts

@@ -0,0 +1,195 @@
+import type {
+  SearchPapersOptions,
+  SearchPapersResponse,
+  GetPaperOptions,
+  PaperMetadataResponse,
+  ReadPaperResponse,
+  SimilarPapersOptions,
+  SimilarPapersResponse,
+  SearchGithubOptions,
+  GitHubSearchResponse,
+} from "../types";
+import { SdkError } from "../types";
+import { HttpClient } from "../utils/httpClient";
+import { throwForBadResponse } from "../utils/errorHandler";
+
+const BASE = "/v2/research";
+
+/** Append a value (or repeated array values) to a URLSearchParams instance. */
+function appendParam(
+  params: URLSearchParams,
+  key: string,
+  value: string | number | boolean | string[] | undefined,
+): void {
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    for (const v of value) {
+      if (v != null && String(v).length > 0) params.append(key, String(v));
+    }
+  } else {
+    params.append(key, String(value));
+  }
+}
+
+function withQuery(path: string, params: URLSearchParams): string {
+  const qs = params.toString();
+  return qs ? `${path}?${qs}` : path;
+}
+
+/**
+ * Translate the RFC 7807 Problem body returned by the research service into an
+ * SdkError. Falls back to the generic axios normalization otherwise.
+ */
+function normalizeResearchError(err: any, action: string): never {
+  if (err?.isAxiosError) {
+    const status: number | undefined = err.response?.status;
+    const body: any = err.response?.data;
+    if (body && (body.detail || body.title)) {
+      const message = body.detail || body.title;
+      throw new SdkError(message, status, body.type, body);
+    }
+    throw new SdkError(
+      err.message || `Request failed while trying to ${action}`,
+      status,
+      err.code,
+      body,
+    );
+  }
+  throw err;
+}
+
+/**
+ * Client for the v2 research endpoints (arXiv papers + GitHub history/readmes).
+ * Accessed via `firecrawl.research`.
+ */
+export class ResearchClient {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Search papers by abstract relevance.
+   * @param query Natural-language search query.
+   * @param options Optional filters (k, authors, categories, from, to).
+   */
+  async searchPapers(
+    query: string,
+    options: SearchPapersOptions = {},
+  ): Promise<SearchPapersResponse> {
+    if (!query || !query.trim()) throw new Error("query cannot be empty");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "query", query);
+    appendParam(params, "k", options.k);
+    appendParam(params, "authors", options.authors);
+    appendParam(params, "categories", options.categories);
+    appendParam(params, "from", options.from);
+    appendParam(params, "to", options.to);
+    try {
+      const res = await this.http.get<SearchPapersResponse>(
+        withQuery(`${BASE}/papers`, params),
+      );
+      if (res.status !== 200) throwForBadResponse(res, "search papers");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "search papers");
+    }
+  }
+
+  /**
+   * Get paper metadata (detail mode), or read in-body passages (when `query` is
+   * supplied). `k` is only valid together with `query`.
+   * @param id Paper reference: a canonical `paper_id`, an `arxiv:<id>` key, or a
+   *   bare arXiv id / URL.
+   * @param options Optional `query` (switches to read mode) and `k`.
+   */
+  async getPaper(
+    id: string,
+    options?: { query?: undefined; k?: undefined },
+  ): Promise<PaperMetadataResponse>;
+  async getPaper(
+    id: string,
+    options: { query: string; k?: number },
+  ): Promise<ReadPaperResponse>;
+  async getPaper(
+    id: string,
+    options: GetPaperOptions = {},
+  ): Promise<PaperMetadataResponse | ReadPaperResponse> {
+    if (!id || !id.trim()) throw new Error("id cannot be empty");
+    if (options.k != null && options.query == null)
+      throw new Error("k is only valid together with query");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "query", options.query);
+    appendParam(params, "k", options.k);
+    try {
+      const res = await this.http.get<PaperMetadataResponse | ReadPaperResponse>(
+        withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params),
+      );
+      if (res.status !== 200) throwForBadResponse(res, "get paper");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "get paper");
+    }
+  }
+
+  /**
+   * Find related papers via the citation graph.
+   * @param id Primary seed paper reference.
+   * @param options Required `intent` plus optional mode, k, rerank, anchor.
+   */
+  async similarPapers(
+    id: string,
+    options: SimilarPapersOptions,
+  ): Promise<SimilarPapersResponse> {
+    if (!id || !id.trim()) throw new Error("id cannot be empty");
+    if (!options?.intent || !options.intent.trim())
+      throw new Error("intent cannot be empty");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "intent", options.intent);
+    appendParam(params, "mode", options.mode);
+    appendParam(params, "k", options.k);
+    if (options.rerank != null) appendParam(params, "rerank", options.rerank);
+    appendParam(params, "anchor", options.anchor);
+    try {
+      const res = await this.http.get<SimilarPapersResponse>(
+        withQuery(
+          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
+          params,
+        ),
+      );
+      if (res.status !== 200) throwForBadResponse(res, "find similar papers");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "find similar papers");
+    }
+  }
+
+  /**
+   * Search GitHub issue/PR history and repository readmes.
+   * @param query Search query.
+   * @param options Optional `k`.
+   */
+  async searchGithub(
+    query: string,
+    options: SearchGithubOptions = {},
+  ): Promise<GitHubSearchResponse> {
+    if (!query || !query.trim()) throw new Error("query cannot be empty");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "query", query);
+    appendParam(params, "k", options.k);
+    try {
+      const res = await this.http.get<GitHubSearchResponse>(
+        withQuery(`${BASE}/github`, params),
+      );
+      if (res.status !== 200) throwForBadResponse(res, "search github");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "search github");
+    }
+  }
+}

package/src/v2/types.ts

@@ -14,7 +14,8 @@ export type FormatString =
   | "attributes"
   | "branding"
   | "audio"
-  | "video";
+  | "video"
+  | "pii";
 
 export interface Viewport {
   width: number;
@@ -205,6 +206,7 @@ export interface ScrapeOptions {
   minAge?: number;
   storeInCache?: boolean;
   lockdown?: boolean;
+  redactPII?: boolean | RedactPIIOptions;
   profile?: {
     name: string;
     saveChanges?: boolean;
@@ -213,6 +215,70 @@ export interface ScrapeOptions {
   origin?: string;
 }
 
+export type RedactPIIEntity =
+  | "PERSON"
+  | "EMAIL"
+  | "PHONE"
+  | "LOCATION"
+  | "FINANCIAL"
+  | "SECRET";
+
+export interface RedactPIIOptions {
+  /**
+   * accurate (default): model-only redaction. Best precision, cleanest output.
+   * aggressive: model + Presidio + spaCy. Higher recall at the cost of precision.
+   * fast: Presidio only, no model call. Lower F1, ~2x throughput.
+   */
+  mode?: "accurate" | "aggressive" | "fast";
+  /** Restrict redaction to these entity buckets. Unset means all entities. */
+  entities?: RedactPIIEntity[];
+  /**
+   * tag (default): replace spans with `<KIND>` placeholders.
+   * mask: replace spans with `*` of equal length.
+   * remove: drop span characters entirely.
+   */
+  replaceStyle?: "tag" | "mask" | "remove";
+}
+
+export type PIISource = "model" | "heuristics" | "unknown";
+
+export interface PIISpan {
+  start: number;
+  end: number;
+  /** Unified entity bucket. Omitted when `kind` doesn't map onto one. */
+  entity?: RedactPIIEntity;
+  /** Granular recognizer label from fire-privacy. */
+  kind: string;
+  source: PIISource;
+  /** Confidence in [0, 1] when supplied. */
+  score?: number;
+}
+
+/**
+ * - ok: redaction completed; redactedMarkdown is the result.
+ * - skipped: redaction was not performed; see `reason`.
+ * - failed: redaction was attempted but did not produce a usable result.
+ */
+export type PIIStatus = "ok" | "skipped" | "failed";
+
+/** Always set when status !== "ok". */
+export type PIIReason =
+  | "empty_input"
+  | "too_large"
+  | "upstream_skipped"
+  | "service_unavailable"
+  | "timeout"
+  | "error";
+
+export interface PIIBlock {
+  status: PIIStatus;
+  reason?: PIIReason;
+  redactedMarkdown: string | null;
+  spans: PIISpan[];
+  /** Span count per entity bucket. Only non-zero entries are present. */
+  counts: Partial<Record<RedactPIIEntity, number>>;
+}
+
 export type ParseFileData =
   | Blob
   | File
@@ -483,6 +549,7 @@ export interface Document {
   warning?: string;
   changeTracking?: Record<string, unknown>;
   branding?: BrandingProfile;
+  pii?: PIIBlock;
 }
 
 // Pagination configuration for auto-fetching pages from v2 endpoints that return a `next` URL
@@ -660,6 +727,25 @@ export interface MonitorEmailNotification {
   includeDiffs?: boolean;
 }
 
+/**
+ * Per-recipient opt-in state for monitor email notifications.
+ *
+ * External recipients (not members of the team that owns the monitor) must
+ * confirm their subscription via a one-time email before they receive any
+ * monitor notifications. Team members are auto-confirmed.
+ *
+ * - `pending`      → confirmation email sent, no notifications yet
+ * - `confirmed`    → notifications enabled
+ * - `unsubscribed` → recipient opted out and cannot be re-added without a new
+ *                    confirmation flow
+ */
+export interface MonitorEmailRecipientSubscription {
+  email: string;
+  status: "pending" | "confirmed" | "unsubscribed";
+  source: "team" | "opt_in" | "legacy";
+  confirmationEmailSent?: boolean;
+}
+
 export interface MonitorNotification {
   email?: MonitorEmailNotification;
 }
@@ -731,6 +817,13 @@ export interface Monitor {
   targets: MonitorTarget[];
   webhook?: MonitorWebhookConfig | null;
   notification?: MonitorNotification | null;
+  /**
+   * Present on create/update/get responses. Reflects the opt-in state of every
+   * email recipient currently configured on the monitor. Absent when the API
+   * has not reconciled recipients (e.g. team-default delivery with no
+   * explicit recipients).
+   */
+  emailRecipientSubscriptions?: MonitorEmailRecipientSubscription[];
   retentionDays: number;
   estimatedCreditsPerMonth?: number | null;
   lastCheckSummary?: MonitorSummary | null;
@@ -1062,3 +1155,161 @@ export interface BrowserListResponse {
   sessions?: BrowserSession[];
   error?: string;
 }
+
+// ---------- Research (v2) ----------
+
+/**
+ * Source identifiers grouped by namespace. Currently only `arxiv` is
+ * populated; each value is an array of ids in that namespace.
+ */
+export type IdMap = Record<string, string[]>;
+
+/** Per-candidate ranking signals (present on similarity results). */
+export interface PaperSignals {
+  /** Raw structural strength (co-citation / coupling counts, or seed overlap). */
+  structural: number;
+  /** Semantic score from the intent abstract search (0 if absent). */
+  semantic: number;
+  /** Citation-graph PageRank of the candidate. */
+  pagerank: number;
+  /** Number of distinct seeds connected to this candidate. */
+  seed_overlap: number;
+}
+
+/** A ranked paper. `paper_id` is canonical; arXiv lives in `ids`. */
+export interface PaperResult {
+  /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
+  paper_id: string;
+  ids?: IdMap;
+  title: string;
+  abstract: string;
+  /** Final ranking score (post-rerank when enabled). Not normalized. */
+  score: number;
+  /** Present on similarity results. */
+  signals?: PaperSignals;
+}
+
+export interface PaperMetadata {
+  paper_id: string;
+  ids?: IdMap;
+  title: string;
+  abstract: string;
+  /** Comma-joined author names. Omitted if unknown. */
+  authors?: string;
+  /** arXiv categories. Omitted if unknown. */
+  categories?: string[];
+  /** Original creation date string (format varies). Omitted if unknown. */
+  created_date?: string;
+  /** Last-updated date string. Omitted if unknown. */
+  update_date?: string;
+}
+
+export interface Passage {
+  /** In-body passage text (may be markdown, including tables). */
+  text: string;
+  /** Dense similarity score for the passage. */
+  score: number;
+}
+
+export interface SearchPapersResponse {
+  results: PaperResult[];
+}
+
+export interface PaperMetadataResponse {
+  paper: PaperMetadata;
+}
+
+export interface ReadPaperResponse {
+  paper: PaperMetadata;
+  /** Resolved canonical paper id (empty string if not found via id-key). */
+  paper_id: string;
+  /** Echo of the read query. */
+  query: string;
+  /** Top matching in-body passages. */
+  passages: Passage[];
+}
+
+export interface SimilarPapersResponse {
+  /** Ranked related papers; each carries `signals`. */
+  results: PaperResult[];
+  /** Number of resolved candidates considered before truncation to `k`. */
+  pool_size: number;
+  /** True if more resolved candidates existed than were returned. */
+  truncated: boolean;
+  /** Human-readable note when no results are produced. */
+  note?: string | null;
+}
+
+/** Component scores; each field is present only when that signal contributed. */
+export interface GitHubScoreBreakdown {
+  rrf?: number;
+  semantic?: number;
+  lexical?: number;
+  fusion?: number;
+}
+
+export interface GitHubSearchItem {
+  resultType: "github_history" | "repo_readme";
+  /** `owner/name`. */
+  repo: string;
+  url: string;
+  /** History page type (e.g. `issue`, `pull`). Omitted for readmes. */
+  pageType?: string;
+  /** Issue/PR number. Omitted for readmes. */
+  number?: number;
+  /** Number of matched segments/chunks. Omitted when not applicable. */
+  segmentCount?: number;
+  /** Readme URL (readme results). Omitted otherwise. */
+  readmeUrl?: string;
+  /** Short matched excerpt. */
+  snippet: string;
+  /** Full matched content in markdown. Omitted unless available. */
+  contentMd?: string;
+  scores: GitHubScoreBreakdown;
+}
+
+export interface GitHubSearchResponse {
+  results: GitHubSearchItem[];
+}
+
+/** Options for `research.searchPapers`. */
+export interface SearchPapersOptions {
+  /** Number of results to return (1–500, default 40). */
+  k?: number;
+  /** Author substring filter(s); ALL must match (case-insensitive). */
+  authors?: string[];
+  /** arXiv category filter(s) (e.g. `cs.LG`); ALL must match. */
+  categories?: string[];
+  /** Inclusive lower bound on created/updated date (ISO `YYYY-MM-DD`). */
+  from?: string;
+  /** Inclusive upper bound on created/updated date (lexicographic). */
+  to?: string;
+}
+
+/** Options for `research.getPaper`. */
+export interface GetPaperOptions {
+  /** When present, switches to read mode and returns in-body passages. */
+  query?: string;
+  /** Passage count (read mode only; 1–50, default 4). Requires `query`. */
+  k?: number;
+}
+
+/** Options for `research.similarPapers`. */
+export interface SimilarPapersOptions {
+  /** Natural-language intent used to semantically rerank candidates. Required. */
+  intent: string;
+  /** Traversal mode (default `similar`). */
+  mode?: "similar" | "citers" | "references";
+  /** Number of related papers to return (1–500, default 40). */
+  k?: number;
+  /** Apply an additional ZeroEntropy rerank over the fused candidates. */
+  rerank?: boolean;
+  /** Additional seed paper reference(s), same format as `id`. */
+  anchor?: string[];
+}
+
+/** Options for `research.searchGithub`. */
+export interface SearchGithubOptions {
+  /** Number of results to return (1–100, default 20). */
+  k?: number;
+}