firecrawl 4.26.0 → 4.27.0

package/dist/{chunk-P63N5KWQ.js → chunk-TVFWAIIZ.js}

@@ -12,7 +12,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.26.0",
+      version: "4.27.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.26.0",
+      version: "4.27.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -820,13 +820,52 @@ async function map(http, url, options) {
           description: item.description
         });
     }
-    return { links };
+    return { id: res.data.id, links };
   } catch (err) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;
   }
 }
 
+// src/v2/methods/feedback.ts
+function validateRating(rating) {
+  if (!["good", "partial", "bad"].includes(rating)) {
+    throw new Error("rating must be one of: good, partial, bad");
+  }
+}
+async function feedback(http, request) {
+  if (!request.endpoint) throw new Error("endpoint is required");
+  if (!request.jobId) throw new Error("jobId is required");
+  validateRating(request.rating);
+  try {
+    const res = await http.post("/v2/feedback", request);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "feedback");
+    }
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "feedback");
+    throw err;
+  }
+}
+async function searchFeedback(http, jobId, request) {
+  if (!jobId) throw new Error("jobId is required");
+  validateRating(request.rating);
+  try {
+    const res = await http.post(
+      `/v2/search/${encodeURIComponent(jobId)}/feedback`,
+      request
+    );
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "searchFeedback");
+    }
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "searchFeedback");
+    throw err;
+  }
+}
+
 // src/v2/utils/pagination.ts
 async function fetchAllPages(http, nextUrl, initial, pagination) {
   const docs = initial.slice();
@@ -1437,7 +1476,7 @@ async function getTokenUsageHistorical(http, byApiKey) {
 }
 
 // src/v2/methods/research.ts
-var BASE = "/v2/research";
+var BASE = "/v2/search/research";
 function appendParam(params, key, value) {
   if (value == null) return;
   if (Array.isArray(value)) {
@@ -2008,6 +2047,23 @@ var FirecrawlClient = class {
   async search(query, req = {}) {
     return search(this.http, { query, ...req });
   }
+  /**
+   * Submit feedback for a v2 job.
+   * @param request Feedback payload with endpoint, job id, rating, and supporting signals.
+   * @returns Feedback record and refund details.
+   */
+  async feedback(request) {
+    return feedback(this.http, request);
+  }
+  /**
+   * Submit feedback for a search job.
+   * @param jobId Search job id returned by search.
+   * @param request Search feedback payload.
+   * @returns Feedback record and refund details.
+   */
+  async searchFeedback(jobId, request) {
+    return searchFeedback(this.http, jobId, request);
+  }
   // Research
   /**
    * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).

package/dist/index.d.cts

@@ -505,6 +505,7 @@ interface BatchScrapeJob {
     data: Document[];
 }
 interface MapData {
+    id?: string;
     links: SearchResultWeb[];
 }
 interface MapOptions {
@@ -518,6 +519,45 @@ interface MapOptions {
     origin?: string;
     location?: LocationConfig$1;
 }
+type FeedbackRating = "good" | "partial" | "bad";
+type EndpointFeedbackEndpoint = "search" | "scrape" | "parse" | "map";
+interface FeedbackValuableSource {
+    url: string;
+    reason?: string;
+}
+interface FeedbackMissingContent {
+    topic: string;
+    description?: string;
+}
+interface SearchFeedbackRequest {
+    rating: FeedbackRating;
+    valuableSources?: FeedbackValuableSource[];
+    missingContent?: FeedbackMissingContent[];
+    querySuggestions?: string;
+    integration?: string | null;
+    origin?: string;
+}
+interface EndpointFeedbackRequest extends SearchFeedbackRequest {
+    endpoint: EndpointFeedbackEndpoint;
+    jobId: string;
+    issues?: string[];
+    tags?: string[];
+    note?: string;
+    url?: string;
+    pageNumbers?: number[];
+    /** Small endpoint-specific metadata object. Must be 8KB or smaller. */
+    metadata?: Record<string, unknown>;
+}
+interface FeedbackResponse {
+    success: true;
+    feedbackId: string;
+    creditsRefunded: number;
+    alreadySubmitted?: boolean;
+    dailyCapReached?: boolean;
+    creditsRefundedToday?: number;
+    dailyRefundCap?: number;
+    warning?: string;
+}
 /**
  * Schedule for a monitor.
  *
@@ -900,15 +940,17 @@ interface PaperSignals {
     structural: number;
     /** Semantic score from the intent abstract search (0 if absent). */
     semantic: number;
-    /** Citation-graph PageRank of the candidate. */
-    pagerank: number;
+    /** Citation-graph article-rank score of the candidate. */
+    articleRank: number;
     /** Number of distinct seeds connected to this candidate. */
-    seed_overlap: number;
+    seedOverlap: number;
 }
-/** A ranked paper. `paper_id` is canonical; arXiv lives in `ids`. */
+/** A ranked paper. `paperId` is canonical; arXiv lives in `ids`. */
 interface PaperResult {
     /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
-    paper_id: string;
+    paperId: string;
+    /** Preferred cite/fetch identifier such as `arxiv:<id>`, `pmid:<id>`, or `doi:<id>`. */
+    primaryId: string;
     ids?: IdMap;
     title: string;
     abstract: string;
@@ -918,7 +960,7 @@ interface PaperResult {
     signals?: PaperSignals;
 }
 interface PaperMetadata {
-    paper_id: string;
+    paperId: string;
     ids?: IdMap;
     title: string;
     abstract: string;
@@ -927,9 +969,9 @@ interface PaperMetadata {
     /** arXiv categories. Omitted if unknown. */
     categories?: string[];
     /** Original creation date string (format varies). Omitted if unknown. */
-    created_date?: string;
+    createdDate?: string;
     /** Last-updated date string. Omitted if unknown. */
-    update_date?: string;
+    updateDate?: string;
 }
 interface Passage {
     /** In-body passage text (may be markdown, including tables). */
@@ -938,25 +980,29 @@ interface Passage {
     score: number;
 }
 interface SearchPapersResponse {
+    success: boolean;
     results: PaperResult[];
 }
 interface PaperMetadataResponse {
+    success: boolean;
     paper: PaperMetadata;
 }
 interface ReadPaperResponse {
+    success: boolean;
     paper: PaperMetadata;
     /** Resolved canonical paper id (empty string if not found via id-key). */
-    paper_id: string;
+    paperId: string;
     /** Echo of the read query. */
     query: string;
     /** Top matching in-body passages. */
     passages: Passage[];
 }
 interface SimilarPapersResponse {
+    success: boolean;
     /** Ranked related papers; each carries `signals`. */
     results: PaperResult[];
     /** Number of resolved candidates considered before truncation to `k`. */
-    pool_size: number;
+    poolSize: number;
     /** True if more resolved candidates existed than were returned. */
     truncated: boolean;
     /** Human-readable note when no results are produced. */
@@ -968,10 +1014,11 @@ interface GitHubScoreBreakdown {
     semantic?: number;
     lexical?: number;
     fusion?: number;
+    rerank?: number;
 }
 interface GitHubSearchItem {
-    resultType: "github_history" | "repo_readme";
-    /** `owner/name`. */
+    resultType: "github_history" | "repo_readme" | "web";
+    /** `owner/name`; empty for web results whose URL is not a repo page. */
     repo: string;
     url: string;
     /** History page type (e.g. `issue`, `pull`). Omitted for readmes. */
@@ -982,6 +1029,8 @@ interface GitHubSearchItem {
     segmentCount?: number;
     /** Readme URL (readme results). Omitted otherwise. */
     readmeUrl?: string;
+    /** SERP page title. Only set on web results. */
+    title?: string;
     /** Short matched excerpt. */
     snippet: string;
     /** Full matched content in markdown. Omitted unless available. */
@@ -989,6 +1038,7 @@ interface GitHubSearchItem {
     scores: GitHubScoreBreakdown;
 }
 interface GitHubSearchResponse {
+    success: boolean;
     results: GitHubSearchItem[];
 }
 /** Options for `research.searchPapers`. */
@@ -1271,6 +1321,19 @@ declare class FirecrawlClient {
      * @returns Structured search results.
      */
     search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
+    /**
+     * Submit feedback for a v2 job.
+     * @param request Feedback payload with endpoint, job id, rating, and supporting signals.
+     * @returns Feedback record and refund details.
+     */
+    feedback(request: EndpointFeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Submit feedback for a search job.
+     * @param jobId Search job id returned by search.
+     * @param request Search feedback payload.
+     * @returns Feedback record and refund details.
+     */
+    searchFeedback(jobId: string, request: SearchFeedbackRequest): Promise<FeedbackResponse>;
     /**
      * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
      * Example: `firecrawl.research.searchPapers("diffusion models")`.
@@ -2439,4 +2502,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-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 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 };
+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 EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, 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 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 SearchFeedbackRequest, 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 };

package/dist/index.d.ts

@@ -505,6 +505,7 @@ interface BatchScrapeJob {
     data: Document[];
 }
 interface MapData {
+    id?: string;
     links: SearchResultWeb[];
 }
 interface MapOptions {
@@ -518,6 +519,45 @@ interface MapOptions {
     origin?: string;
     location?: LocationConfig$1;
 }
+type FeedbackRating = "good" | "partial" | "bad";
+type EndpointFeedbackEndpoint = "search" | "scrape" | "parse" | "map";
+interface FeedbackValuableSource {
+    url: string;
+    reason?: string;
+}
+interface FeedbackMissingContent {
+    topic: string;
+    description?: string;
+}
+interface SearchFeedbackRequest {
+    rating: FeedbackRating;
+    valuableSources?: FeedbackValuableSource[];
+    missingContent?: FeedbackMissingContent[];
+    querySuggestions?: string;
+    integration?: string | null;
+    origin?: string;
+}
+interface EndpointFeedbackRequest extends SearchFeedbackRequest {
+    endpoint: EndpointFeedbackEndpoint;
+    jobId: string;
+    issues?: string[];
+    tags?: string[];
+    note?: string;
+    url?: string;
+    pageNumbers?: number[];
+    /** Small endpoint-specific metadata object. Must be 8KB or smaller. */
+    metadata?: Record<string, unknown>;
+}
+interface FeedbackResponse {
+    success: true;
+    feedbackId: string;
+    creditsRefunded: number;
+    alreadySubmitted?: boolean;
+    dailyCapReached?: boolean;
+    creditsRefundedToday?: number;
+    dailyRefundCap?: number;
+    warning?: string;
+}
 /**
  * Schedule for a monitor.
  *
@@ -900,15 +940,17 @@ interface PaperSignals {
     structural: number;
     /** Semantic score from the intent abstract search (0 if absent). */
     semantic: number;
-    /** Citation-graph PageRank of the candidate. */
-    pagerank: number;
+    /** Citation-graph article-rank score of the candidate. */
+    articleRank: number;
     /** Number of distinct seeds connected to this candidate. */
-    seed_overlap: number;
+    seedOverlap: number;
 }
-/** A ranked paper. `paper_id` is canonical; arXiv lives in `ids`. */
+/** A ranked paper. `paperId` is canonical; arXiv lives in `ids`. */
 interface PaperResult {
     /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
-    paper_id: string;
+    paperId: string;
+    /** Preferred cite/fetch identifier such as `arxiv:<id>`, `pmid:<id>`, or `doi:<id>`. */
+    primaryId: string;
     ids?: IdMap;
     title: string;
     abstract: string;
@@ -918,7 +960,7 @@ interface PaperResult {
     signals?: PaperSignals;
 }
 interface PaperMetadata {
-    paper_id: string;
+    paperId: string;
     ids?: IdMap;
     title: string;
     abstract: string;
@@ -927,9 +969,9 @@ interface PaperMetadata {
     /** arXiv categories. Omitted if unknown. */
     categories?: string[];
     /** Original creation date string (format varies). Omitted if unknown. */
-    created_date?: string;
+    createdDate?: string;
     /** Last-updated date string. Omitted if unknown. */
-    update_date?: string;
+    updateDate?: string;
 }
 interface Passage {
     /** In-body passage text (may be markdown, including tables). */
@@ -938,25 +980,29 @@ interface Passage {
     score: number;
 }
 interface SearchPapersResponse {
+    success: boolean;
     results: PaperResult[];
 }
 interface PaperMetadataResponse {
+    success: boolean;
     paper: PaperMetadata;
 }
 interface ReadPaperResponse {
+    success: boolean;
     paper: PaperMetadata;
     /** Resolved canonical paper id (empty string if not found via id-key). */
-    paper_id: string;
+    paperId: string;
     /** Echo of the read query. */
     query: string;
     /** Top matching in-body passages. */
     passages: Passage[];
 }
 interface SimilarPapersResponse {
+    success: boolean;
     /** Ranked related papers; each carries `signals`. */
     results: PaperResult[];
     /** Number of resolved candidates considered before truncation to `k`. */
-    pool_size: number;
+    poolSize: number;
     /** True if more resolved candidates existed than were returned. */
     truncated: boolean;
     /** Human-readable note when no results are produced. */
@@ -968,10 +1014,11 @@ interface GitHubScoreBreakdown {
     semantic?: number;
     lexical?: number;
     fusion?: number;
+    rerank?: number;
 }
 interface GitHubSearchItem {
-    resultType: "github_history" | "repo_readme";
-    /** `owner/name`. */
+    resultType: "github_history" | "repo_readme" | "web";
+    /** `owner/name`; empty for web results whose URL is not a repo page. */
     repo: string;
     url: string;
     /** History page type (e.g. `issue`, `pull`). Omitted for readmes. */
@@ -982,6 +1029,8 @@ interface GitHubSearchItem {
     segmentCount?: number;
     /** Readme URL (readme results). Omitted otherwise. */
     readmeUrl?: string;
+    /** SERP page title. Only set on web results. */
+    title?: string;
     /** Short matched excerpt. */
     snippet: string;
     /** Full matched content in markdown. Omitted unless available. */
@@ -989,6 +1038,7 @@ interface GitHubSearchItem {
     scores: GitHubScoreBreakdown;
 }
 interface GitHubSearchResponse {
+    success: boolean;
     results: GitHubSearchItem[];
 }
 /** Options for `research.searchPapers`. */
@@ -1271,6 +1321,19 @@ declare class FirecrawlClient {
      * @returns Structured search results.
      */
     search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
+    /**
+     * Submit feedback for a v2 job.
+     * @param request Feedback payload with endpoint, job id, rating, and supporting signals.
+     * @returns Feedback record and refund details.
+     */
+    feedback(request: EndpointFeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Submit feedback for a search job.
+     * @param jobId Search job id returned by search.
+     * @param request Search feedback payload.
+     * @returns Feedback record and refund details.
+     */
+    searchFeedback(jobId: string, request: SearchFeedbackRequest): Promise<FeedbackResponse>;
     /**
      * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
      * Example: `firecrawl.research.searchPapers("diffusion models")`.
@@ -2439,4 +2502,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-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 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 };
+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 EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, 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 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 SearchFeedbackRequest, 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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-P63N5KWQ.js";
+} from "./chunk-TVFWAIIZ.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -688,13 +688,52 @@ async function map(http, url, options) {
           description: item.description
         });
     }
-    return { links };
+    return { id: res.data.id, links };
   } catch (err) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;
   }
 }
 
+// src/v2/methods/feedback.ts
+function validateRating(rating) {
+  if (!["good", "partial", "bad"].includes(rating)) {
+    throw new Error("rating must be one of: good, partial, bad");
+  }
+}
+async function feedback(http, request) {
+  if (!request.endpoint) throw new Error("endpoint is required");
+  if (!request.jobId) throw new Error("jobId is required");
+  validateRating(request.rating);
+  try {
+    const res = await http.post("/v2/feedback", request);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "feedback");
+    }
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "feedback");
+    throw err;
+  }
+}
+async function searchFeedback(http, jobId, request) {
+  if (!jobId) throw new Error("jobId is required");
+  validateRating(request.rating);
+  try {
+    const res = await http.post(
+      `/v2/search/${encodeURIComponent(jobId)}/feedback`,
+      request
+    );
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "searchFeedback");
+    }
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "searchFeedback");
+    throw err;
+  }
+}
+
 // src/v2/utils/pagination.ts
 async function fetchAllPages(http, nextUrl, initial, pagination) {
   const docs = initial.slice();
@@ -1305,7 +1344,7 @@ async function getTokenUsageHistorical(http, byApiKey) {
 }
 
 // src/v2/methods/research.ts
-var BASE = "/v2/research";
+var BASE = "/v2/search/research";
 function appendParam(params, key, value) {
   if (value == null) return;
   if (Array.isArray(value)) {
@@ -1876,6 +1915,23 @@ var FirecrawlClient = class {
   async search(query, req = {}) {
     return search(this.http, { query, ...req });
   }
+  /**
+   * Submit feedback for a v2 job.
+   * @param request Feedback payload with endpoint, job id, rating, and supporting signals.
+   * @returns Feedback record and refund details.
+   */
+  async feedback(request) {
+    return feedback(this.http, request);
+  }
+  /**
+   * Submit feedback for a search job.
+   * @param jobId Search job id returned by search.
+   * @param request Search feedback payload.
+   * @returns Feedback record and refund details.
+   */
+  async searchFeedback(jobId, request) {
+    return searchFeedback(this.http, jobId, request);
+  }
   // Research
   /**
    * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
@@ -2244,7 +2300,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-VYUXJRD4.js");
+      const packageJson = await import("./package-JE2ZVGM4.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-VYUXJRD4.js → package-JE2ZVGM4.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-P63N5KWQ.js";
+} from "./chunk-TVFWAIIZ.js";
 export default require_package();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.26.0",
+  "version": "4.27.0",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -39,7 +39,7 @@ describe("research.searchPapers", () => {
       to: "2024-12-31",
     });
     const url = calls[0];
-    expect(url.startsWith("/v2/research/papers?")).toBe(true);
+    expect(url.startsWith("/v2/search/research/papers?")).toBe(true);
     const qs = new URLSearchParams(url.split("?")[1]);
     expect(qs.get("query")).toBe("diffusion models");
     expect(qs.get("k")).toBe("10");
@@ -67,7 +67,7 @@ describe("research.searchPapers", () => {
   });
 
   test("returns the response body verbatim", async () => {
-    const payload = { results: [{ paper_id: "1", title: "t", abstract: "a", score: 0.1 }] };
+    const payload = { results: [{ paperId: "1", title: "t", abstract: "a", score: 0.1 }] };
     const { client } = makeClient(() => ({ status: 200, data: payload }));
     await expect(client.searchPapers("q")).resolves.toEqual(payload);
   });
@@ -77,17 +77,17 @@ 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");
+    expect(calls[0]).toBe("/v2/search/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: [] },
+      data: { paper: {}, paperId: "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");
+    expect(path).toBe("/v2/search/research/papers/123");
     const qs = new URLSearchParams(query);
     expect(qs.get("query")).toBe("noise schedule");
     expect(qs.get("k")).toBe("4");
@@ -112,7 +112,7 @@ describe("research.similarPapers", () => {
   test("builds path and query with repeated anchors and rerank", async () => {
     const { client, calls } = makeClient(() => ({
       status: 200,
-      data: { results: [], pool_size: 0, truncated: false },
+      data: { results: [], poolSize: 0, truncated: false },
     }));
     await client.similarPapers("2105.05233", {
       intent: "diffusion image synthesis",
@@ -122,7 +122,7 @@ describe("research.similarPapers", () => {
       anchor: ["arxiv:2006.11239", "1503.03585"],
     });
     const [path, query] = calls[0].split("?");
-    expect(path).toBe("/v2/research/papers/2105.05233/similar");
+    expect(path).toBe("/v2/search/research/papers/2105.05233/similar");
     const qs = new URLSearchParams(query);
     expect(qs.get("intent")).toBe("diffusion image synthesis");
     expect(qs.get("mode")).toBe("citers");
@@ -137,7 +137,7 @@ describe("research.searchGithub", () => {
     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(calls[0].startsWith("/v2/search/research/github?")).toBe(true);
     expect(qs.get("query")).toBe("milvus hybrid search");
     expect(qs.get("k")).toBe("10");
   });

package/src/v2/client.ts

@@ -7,6 +7,7 @@ import {
 import { parse as parseMethod } from "./methods/parse";
 import { search } from "./methods/search";
 import { map as mapMethod } from "./methods/map";
+import { feedback as feedbackMethod, searchFeedback as searchFeedbackMethod } from "./methods/feedback";
 import {
   startCrawl,
   getCrawlStatus,
@@ -50,6 +51,9 @@ import type {
   ScrapeOptions,
   SearchData,
   SearchRequest,
+  EndpointFeedbackRequest,
+  FeedbackResponse,
+  SearchFeedbackRequest,
   MapData,
   MapOptions,
   CrawlResponse,
@@ -236,6 +240,25 @@ export class FirecrawlClient {
     return search(this.http, { query, ...req });
   }
 
+  /**
+   * Submit feedback for a v2 job.
+   * @param request Feedback payload with endpoint, job id, rating, and supporting signals.
+   * @returns Feedback record and refund details.
+   */
+  async feedback(request: EndpointFeedbackRequest): Promise<FeedbackResponse> {
+    return feedbackMethod(this.http, request);
+  }
+
+  /**
+   * Submit feedback for a search job.
+   * @param jobId Search job id returned by search.
+   * @param request Search feedback payload.
+   * @returns Feedback record and refund details.
+   */
+  async searchFeedback(jobId: string, request: SearchFeedbackRequest): Promise<FeedbackResponse> {
+    return searchFeedbackMethod(this.http, jobId, request);
+  }
+
   // Research
   /**
    * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
@@ -618,4 +641,3 @@ export class FirecrawlClient {
 }
 
 export default FirecrawlClient;
-

package/src/v2/methods/feedback.ts

@@ -0,0 +1,59 @@
+import {
+  type EndpointFeedbackRequest,
+  type FeedbackResponse,
+  type SearchFeedbackRequest,
+} from "../types";
+import { HttpClient } from "../utils/httpClient";
+import {
+  normalizeAxiosError,
+  throwForBadResponse,
+} from "../utils/errorHandler";
+
+function validateRating(rating: string): void {
+  if (!["good", "partial", "bad"].includes(rating)) {
+    throw new Error("rating must be one of: good, partial, bad");
+  }
+}
+
+export async function feedback(
+  http: HttpClient,
+  request: EndpointFeedbackRequest,
+): Promise<FeedbackResponse> {
+  if (!request.endpoint) throw new Error("endpoint is required");
+  if (!request.jobId) throw new Error("jobId is required");
+  validateRating(request.rating);
+
+  try {
+    const res = await http.post<FeedbackResponse>("/v2/feedback", request);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "feedback");
+    }
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "feedback");
+    throw err;
+  }
+}
+
+export async function searchFeedback(
+  http: HttpClient,
+  jobId: string,
+  request: SearchFeedbackRequest,
+): Promise<FeedbackResponse> {
+  if (!jobId) throw new Error("jobId is required");
+  validateRating(request.rating);
+
+  try {
+    const res = await http.post<FeedbackResponse>(
+      `/v2/search/${encodeURIComponent(jobId)}/feedback`,
+      request,
+    );
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "searchFeedback");
+    }
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "searchFeedback");
+    throw err;
+  }
+}

package/src/v2/methods/map.ts

@@ -37,6 +37,7 @@ export async function map(
   try {
     const res = await http.post<{
       success: boolean;
+      id?: string;
       error?: string;
       links?: Array<string | SearchResultWeb>;
     }>(
@@ -60,7 +61,7 @@ export async function map(
           description: (item as any).description,
         });
     }
-    return { links };
+    return { id: res.data.id, links };
   } catch (err: any) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;

package/src/v2/methods/research.ts

@@ -13,7 +13,7 @@ import { SdkError } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { throwForBadResponse } from "../utils/errorHandler";
 
-const BASE = "/v2/research";
+const BASE = "/v2/search/research";
 
 /** Append a value (or repeated array values) to a URLSearchParams instance. */
 function appendParam(

package/src/v2/types.ts

@@ -647,6 +647,7 @@ export interface BatchScrapeJob {
 }
 
 export interface MapData {
+  id?: string;
   links: SearchResultWeb[];
 }
 
@@ -662,6 +663,51 @@ export interface MapOptions {
   location?: LocationConfig;
 }
 
+export type FeedbackRating = "good" | "partial" | "bad";
+export type EndpointFeedbackEndpoint = "search" | "scrape" | "parse" | "map";
+
+export interface FeedbackValuableSource {
+  url: string;
+  reason?: string;
+}
+
+export interface FeedbackMissingContent {
+  topic: string;
+  description?: string;
+}
+
+export interface SearchFeedbackRequest {
+  rating: FeedbackRating;
+  valuableSources?: FeedbackValuableSource[];
+  missingContent?: FeedbackMissingContent[];
+  querySuggestions?: string;
+  integration?: string | null;
+  origin?: string;
+}
+
+export interface EndpointFeedbackRequest extends SearchFeedbackRequest {
+  endpoint: EndpointFeedbackEndpoint;
+  jobId: string;
+  issues?: string[];
+  tags?: string[];
+  note?: string;
+  url?: string;
+  pageNumbers?: number[];
+  /** Small endpoint-specific metadata object. Must be 8KB or smaller. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface FeedbackResponse {
+  success: true;
+  feedbackId: string;
+  creditsRefunded: number;
+  alreadySubmitted?: boolean;
+  dailyCapReached?: boolean;
+  creditsRefundedToday?: number;
+  dailyRefundCap?: number;
+  warning?: string;
+}
+
 /**
  * Schedule for a monitor.
  *
@@ -1129,16 +1175,18 @@ export interface PaperSignals {
   structural: number;
   /** Semantic score from the intent abstract search (0 if absent). */
   semantic: number;
-  /** Citation-graph PageRank of the candidate. */
-  pagerank: number;
+  /** Citation-graph article-rank score of the candidate. */
+  articleRank: number;
   /** Number of distinct seeds connected to this candidate. */
-  seed_overlap: number;
+  seedOverlap: number;
 }
 
-/** A ranked paper. `paper_id` is canonical; arXiv lives in `ids`. */
+/** A ranked paper. `paperId` is canonical; arXiv lives in `ids`. */
 export interface PaperResult {
   /** Canonical paper id — the Milvus INT64 primary key as a decimal string. */
-  paper_id: string;
+  paperId: string;
+  /** Preferred cite/fetch identifier such as `arxiv:<id>`, `pmid:<id>`, or `doi:<id>`. */
+  primaryId: string;
   ids?: IdMap;
   title: string;
   abstract: string;
@@ -1149,7 +1197,7 @@ export interface PaperResult {
 }
 
 export interface PaperMetadata {
-  paper_id: string;
+  paperId: string;
   ids?: IdMap;
   title: string;
   abstract: string;
@@ -1158,9 +1206,9 @@ export interface PaperMetadata {
   /** arXiv categories. Omitted if unknown. */
   categories?: string[];
   /** Original creation date string (format varies). Omitted if unknown. */
-  created_date?: string;
+  createdDate?: string;
   /** Last-updated date string. Omitted if unknown. */
-  update_date?: string;
+  updateDate?: string;
 }
 
 export interface Passage {
@@ -1171,17 +1219,20 @@ export interface Passage {
 }
 
 export interface SearchPapersResponse {
+  success: boolean;
   results: PaperResult[];
 }
 
 export interface PaperMetadataResponse {
+  success: boolean;
   paper: PaperMetadata;
 }
 
 export interface ReadPaperResponse {
+  success: boolean;
   paper: PaperMetadata;
   /** Resolved canonical paper id (empty string if not found via id-key). */
-  paper_id: string;
+  paperId: string;
   /** Echo of the read query. */
   query: string;
   /** Top matching in-body passages. */
@@ -1189,10 +1240,11 @@ export interface ReadPaperResponse {
 }
 
 export interface SimilarPapersResponse {
+  success: boolean;
   /** Ranked related papers; each carries `signals`. */
   results: PaperResult[];
   /** Number of resolved candidates considered before truncation to `k`. */
-  pool_size: number;
+  poolSize: number;
   /** True if more resolved candidates existed than were returned. */
   truncated: boolean;
   /** Human-readable note when no results are produced. */
@@ -1205,11 +1257,12 @@ export interface GitHubScoreBreakdown {
   semantic?: number;
   lexical?: number;
   fusion?: number;
+  rerank?: number;
 }
 
 export interface GitHubSearchItem {
-  resultType: "github_history" | "repo_readme";
-  /** `owner/name`. */
+  resultType: "github_history" | "repo_readme" | "web";
+  /** `owner/name`; empty for web results whose URL is not a repo page. */
   repo: string;
   url: string;
   /** History page type (e.g. `issue`, `pull`). Omitted for readmes. */
@@ -1220,6 +1273,8 @@ export interface GitHubSearchItem {
   segmentCount?: number;
   /** Readme URL (readme results). Omitted otherwise. */
   readmeUrl?: string;
+  /** SERP page title. Only set on web results. */
+  title?: string;
   /** Short matched excerpt. */
   snippet: string;
   /** Full matched content in markdown. Omitted unless available. */
@@ -1228,6 +1283,7 @@ export interface GitHubSearchItem {
 }
 
 export interface GitHubSearchResponse {
+  success: boolean;
   results: GitHubSearchItem[];
 }