firecrawl 4.25.2 → 4.25.3

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

@@ -1155,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;
+}