@mendable/firecrawl-js 4.38.0 → 4.39.0

package/README.md

@@ -261,8 +261,13 @@ const related = await app.research.similarPapers('pmid:<id>', {
 });
 ```
 
-A companion `app.research.searchGithub` searches indexed GitHub issue/PR history
-and repository readmes.
+> **`app.research.searchGithub` is deprecated.** The research index GitHub
+> endpoint stops responding after 2026-11-03. Use `app.developerSearch`
+> instead: it searches GitHub issues, pull requests and readmes plus curated
+> documentation sources, returns matched passages, and adds filters for repo,
+> language, license and stars. It does not carry over the `scores` breakdown
+> or the `resultType: "web"` fallback results. See
+> [the developer index docs](https://docs.firecrawl.dev/features/developer).
 
 ### Scrape-bound interactive browsing (v2)
 

package/dist/{chunk-KSTNOGOD.js → chunk-4DPCCKWG.js}

@@ -12,7 +12,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.38.0",
+      version: "4.39.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       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.38.0",
+      version: "4.39.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -751,6 +751,7 @@ function prepareSearchPayload(req) {
   if (req.limit != null) payload.limit = req.limit;
   if (req.tbs != null) payload.tbs = req.tbs;
   if (req.location != null) payload.location = req.location;
+  if (req.country != null) payload.country = req.country;
   if (req.ignoreInvalidURLs != null)
     payload.ignoreInvalidURLs = req.ignoreInvalidURLs;
   if (req.timeout != null) payload.timeout = req.timeout;
@@ -1371,6 +1372,9 @@ function prepareAgentPayload(args) {
     body.threatProtection = args.threatProtection;
   if (args.auditMetadata != null)
     body.auditMetadata = args.auditMetadata;
+  if (args.threadId != null) body.threadId = args.threadId;
+  if (args.mode != null) body.mode = args.mode;
+  if (args.exchange != null) body.exchange = args.exchange;
   return body;
 }
 async function startAgent(http, args) {
@@ -1441,6 +1445,17 @@ async function getAgentSnapshot(http, jobId, snapshotId) {
     throw err;
   }
 }
+async function getAgentThread(http, threadId, options) {
+  try {
+    const query = options?.includeData ? "?includeData=true" : "";
+    const res = await http.get(`/v2/agent/threads/${threadId}${query}`);
+    if (res.status !== 200) throwForBadResponse(res, "agent thread");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent thread");
+    throw err;
+  }
+}
 async function cancelAgent(http, jobId) {
   try {
     const res = await http.delete(`/v2/agent/${jobId}`);
@@ -1681,9 +1696,7 @@ var ResearchClient = class {
     appendParam(params, "query", options.query);
     appendParam(params, "k", options.k);
     try {
-      const res = await this.http.get(
-        withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params)
-      );
+      const res = await this.http.get(withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params));
       if (res.status !== 200) throwForBadResponse(res, "get paper");
       return res.data;
     } catch (err) {
@@ -1709,10 +1722,7 @@ var ResearchClient = class {
     appendParam(params, "anchor", options.anchor);
     try {
       const res = await this.http.get(
-        withQuery(
-          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
-          params
-        )
+        withQuery(`${BASE}/papers/${encodeURIComponent(id)}/similar`, params)
       );
       if (res.status !== 200) throwForBadResponse(res, "find similar papers");
       return res.data;
@@ -1721,7 +1731,16 @@ var ResearchClient = class {
     }
   }
   /**
-   * Search GitHub issue/PR history and repository readmes.
+   * Search the research index GitHub slice: issue/PR history and repository
+   * readmes.
+   *
+   * @deprecated Use `developerSearch()` on the client instead. This
+   * endpoint stops responding after 2026-11-03. The developer index searches
+   * GitHub issues, pull requests and readmes plus curated documentation
+   * sources, returns matched passages, and adds filters for repo, language,
+   * license and stars. It does not carry over the `scores` breakdown or the
+   * `resultType: "web"` fallback results. See
+   * https://docs.firecrawl.dev/features/developer.
    * @param query Search query.
    * @param options Optional `k`.
    */
@@ -2210,6 +2229,9 @@ var FirecrawlClient = class {
    * Access the v2 research endpoints — Firecrawl's **research paper index**
    * (~43M paper abstracts) plus GitHub history/readmes.
    *
+   * `research.searchGithub()` is deprecated and stops responding after
+   * 2026-11-03. Use `developerSearch()` instead.
+   *
    * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
    * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
    * computer science.
@@ -2469,6 +2491,14 @@ var FirecrawlClient = class {
   async getAgentSnapshot(jobId, snapshotId) {
     return getAgentSnapshot(this.http, jobId, snapshotId);
   }
+  /**
+   * Get a thread and its runs, oldest turn first.
+   * @param threadId Thread id, as returned by startAgent or getAgentStatus.
+   * @param options.includeData Inline each succeeded run's data.
+   */
+  async getAgentThread(threadId, options) {
+    return getAgentThread(this.http, threadId, options);
+  }
   // Browser
   /**
    * Create a new browser session.

package/dist/index.d.cts

@@ -698,6 +698,8 @@ interface SearchRequest {
     limit?: number;
     tbs?: string;
     location?: string;
+    /** ISO 3166-1 alpha-2 country code used to geo-target the search results. */
+    country?: string;
     ignoreInvalidURLs?: boolean;
     timeout?: number;
     /** Generate query-relevant highlights for search results. Defaults to true. */
@@ -1087,10 +1089,66 @@ interface ExtractResponse$1 {
     expiresAt?: string;
     creditsUsed?: number;
 }
+/** Conversation mode for an agent run. Defaults to "extract" server-side. */
+type AgentMode = "extract" | "chat";
+/** Options forwarded verbatim to the agent; the server owns every default. */
+interface AgentExchangeOptions {
+    enabled?: boolean;
+    /** At most 5. */
+    toolkits?: string[];
+    maxCalls?: number;
+    requireApproval?: boolean;
+    /** Answers a pendingApproval from the previous turn of the thread. */
+    approve?: {
+        approvalId: string;
+        callIds?: string[];
+        always?: boolean;
+    };
+    decline?: {
+        approvalId: string;
+    };
+}
+/** Per-run summary reported on a status response. */
+interface AgentExchangeSummary {
+    enabled: boolean;
+    /** What the run resolved to after thread inheritance, not what it requested. */
+    toolkits?: string[];
+    requireApproval?: boolean;
+    paidCalls: number;
+    creditsUsed: number | null;
+}
+/** A follow-up the agent offers for the next turn of the thread. */
+interface AgentSuggestion {
+    label: string;
+    prompt: string;
+}
+/** A turn that ended waiting for the caller to allow or refuse paid calls. */
+interface PendingApproval {
+    id: string;
+    reason: string;
+    calls: {
+        id: string;
+        provider: string;
+        capability: string;
+        input: Record<string, unknown>;
+        more?: Record<string, unknown>[];
+        creditsEstimate: number | null;
+    }[];
+    resolution: null | {
+        approved: boolean;
+        callIds: string[];
+        always: boolean;
+        byRunId: string;
+    };
+}
 interface AgentResponse {
     success: boolean;
     id: string;
     error?: string;
+    /** Thread this run belongs to; pass it back to continue the conversation. */
+    threadId?: string;
+    /** 1-based position of this run in its thread. */
+    threadTurn?: number;
 }
 interface AgentStatusResponse {
     success: boolean;
@@ -1110,6 +1168,46 @@ interface AgentStatusResponse {
     effort?: "low" | "medium" | "high";
     expiresAt: string;
     creditsUsed?: number;
+    threadId?: string;
+    threadTurn?: number;
+    mode?: AgentMode;
+    /** Assistant text reply. Chat-mode runs answer here instead of in `data`. */
+    message?: string;
+    suggestions?: AgentSuggestion[];
+    pendingApproval?: PendingApproval;
+    exchange?: AgentExchangeSummary;
+}
+/** A single run of a thread, as returned by getAgentThread. */
+interface AgentThreadRun {
+    id: string;
+    turn: number;
+    mode: AgentMode;
+    prompt: string;
+    urls?: string[];
+    schema?: unknown;
+    effort?: "low" | "medium" | "high";
+    status: "processing" | "succeeded" | "failed" | "cancelled" | "refused" | "credit_limit_reached";
+    createdAt: string;
+    finishedAt: string | null;
+    creditsUsed: number | null;
+    message: string | null;
+    /** Only present when the request asked for includeData. */
+    data?: unknown;
+    suggestions?: AgentSuggestion[] | null;
+    pendingApproval?: PendingApproval | null;
+    exchange?: AgentExchangeSummary | null;
+}
+interface AgentThread {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    status: "idle" | "running";
+    runs: AgentThreadRun[];
+}
+interface AgentThreadResponse {
+    success: boolean;
+    thread?: AgentThread;
+    error?: string;
 }
 /** Reasoning effort for agent jobs. Every level runs spark-2. */
 type AgentEffort = "low" | "medium" | "high";
@@ -1505,7 +1603,14 @@ interface SimilarPapersResponse {
     /** Human-readable note when no results are produced. */
     note?: string | null;
 }
-/** Component scores; each field is present only when that signal contributed. */
+/**
+ * Component scores; each field is present only when that signal contributed.
+ *
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. The developer index does not
+ * expose a score breakdown. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface GitHubScoreBreakdown {
     rrf?: number;
     semantic?: number;
@@ -1513,6 +1618,11 @@ interface GitHubScoreBreakdown {
     fusion?: number;
     rerank?: number;
 }
+/**
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface GitHubSearchItem {
     resultType?: "github_history" | "repo_readme" | "web";
     /** `owner/name`; empty for web results whose URL is not a repo page. */
@@ -1534,9 +1644,18 @@ interface GitHubSearchItem {
     contentMd?: string;
     scores: GitHubScoreBreakdown;
 }
+/**
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface GitHubSearchResponse {
     success: boolean;
     results: GitHubSearchItem[];
+    /** Deprecation notice while the sunset window is live. */
+    warnings?: string[];
+    /** Replacement endpoint path, while the sunset window is live. */
+    replacement?: string;
 }
 /** Options for `research.searchPapers`. */
 interface SearchPapersOptions {
@@ -1571,7 +1690,13 @@ interface SimilarPapersOptions {
     /** Additional seed paper reference(s), same format as `id`. */
     anchor?: string[];
 }
-/** Options for `research.searchGithub`. */
+/**
+ * Options for `research.searchGithub`.
+ *
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface SearchGithubOptions {
     /** Number of results to return (1–100, default 20). */
     k?: number;
@@ -1666,6 +1791,9 @@ declare function prepareAgentPayload(args: {
     webhook?: string | AgentWebhookConfig;
     threatProtection?: ThreatProtectionOptions;
     auditMetadata?: AuditMetadata$1;
+    threadId?: string;
+    mode?: AgentMode;
+    exchange?: AgentExchangeOptions;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -1756,7 +1884,16 @@ declare class ResearchClient {
      */
     similarPapers(id: string, options: SimilarPapersOptions): Promise<SimilarPapersResponse>;
     /**
-     * Search GitHub issue/PR history and repository readmes.
+     * Search the research index GitHub slice: issue/PR history and repository
+     * readmes.
+     *
+     * @deprecated Use `developerSearch()` on the client instead. This
+     * endpoint stops responding after 2026-11-03. The developer index searches
+     * GitHub issues, pull requests and readmes plus curated documentation
+     * sources, returns matched passages, and adds filters for repo, language,
+     * license and stars. It does not carry over the `scores` breakdown or the
+     * `resultType: "web"` fallback results. See
+     * https://docs.firecrawl.dev/features/developer.
      * @param query Search query.
      * @param options Optional `k`.
      */
@@ -1903,6 +2040,9 @@ declare class FirecrawlClient {
      * Access the v2 research endpoints — Firecrawl's **research paper index**
      * (~43M paper abstracts) plus GitHub history/readmes.
      *
+     * `research.searchGithub()` is deprecated and stops responding after
+     * 2026-11-03. Use `developerSearch()` instead.
+     *
      * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
      * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
      * computer science.
@@ -2105,6 +2245,14 @@ declare class FirecrawlClient {
      * @param snapshotId Snapshot id from an artifact.updated trace event.
      */
     getAgentSnapshot(jobId: string, snapshotId: string): Promise<AgentSnapshotResponse>;
+    /**
+     * Get a thread and its runs, oldest turn first.
+     * @param threadId Thread id, as returned by startAgent or getAgentStatus.
+     * @param options.includeData Inline each succeeded run's data.
+     */
+    getAgentThread(threadId: string, options?: {
+        includeData?: boolean;
+    }): Promise<AgentThreadResponse>;
     /**
      * Create a new browser session.
      * @param args Session options (ttl, activityTtl, streamWebView, profile).
@@ -3107,4 +3255,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, 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 DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, 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 MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, 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 PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, 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 ThreatProtectionOptions, 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 AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentThread, type AgentThreadResponse, type AgentThreadRun, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, 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 DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, 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 MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, 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 PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, 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 ThreatProtectionOptions, 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

@@ -698,6 +698,8 @@ interface SearchRequest {
     limit?: number;
     tbs?: string;
     location?: string;
+    /** ISO 3166-1 alpha-2 country code used to geo-target the search results. */
+    country?: string;
     ignoreInvalidURLs?: boolean;
     timeout?: number;
     /** Generate query-relevant highlights for search results. Defaults to true. */
@@ -1087,10 +1089,66 @@ interface ExtractResponse$1 {
     expiresAt?: string;
     creditsUsed?: number;
 }
+/** Conversation mode for an agent run. Defaults to "extract" server-side. */
+type AgentMode = "extract" | "chat";
+/** Options forwarded verbatim to the agent; the server owns every default. */
+interface AgentExchangeOptions {
+    enabled?: boolean;
+    /** At most 5. */
+    toolkits?: string[];
+    maxCalls?: number;
+    requireApproval?: boolean;
+    /** Answers a pendingApproval from the previous turn of the thread. */
+    approve?: {
+        approvalId: string;
+        callIds?: string[];
+        always?: boolean;
+    };
+    decline?: {
+        approvalId: string;
+    };
+}
+/** Per-run summary reported on a status response. */
+interface AgentExchangeSummary {
+    enabled: boolean;
+    /** What the run resolved to after thread inheritance, not what it requested. */
+    toolkits?: string[];
+    requireApproval?: boolean;
+    paidCalls: number;
+    creditsUsed: number | null;
+}
+/** A follow-up the agent offers for the next turn of the thread. */
+interface AgentSuggestion {
+    label: string;
+    prompt: string;
+}
+/** A turn that ended waiting for the caller to allow or refuse paid calls. */
+interface PendingApproval {
+    id: string;
+    reason: string;
+    calls: {
+        id: string;
+        provider: string;
+        capability: string;
+        input: Record<string, unknown>;
+        more?: Record<string, unknown>[];
+        creditsEstimate: number | null;
+    }[];
+    resolution: null | {
+        approved: boolean;
+        callIds: string[];
+        always: boolean;
+        byRunId: string;
+    };
+}
 interface AgentResponse {
     success: boolean;
     id: string;
     error?: string;
+    /** Thread this run belongs to; pass it back to continue the conversation. */
+    threadId?: string;
+    /** 1-based position of this run in its thread. */
+    threadTurn?: number;
 }
 interface AgentStatusResponse {
     success: boolean;
@@ -1110,6 +1168,46 @@ interface AgentStatusResponse {
     effort?: "low" | "medium" | "high";
     expiresAt: string;
     creditsUsed?: number;
+    threadId?: string;
+    threadTurn?: number;
+    mode?: AgentMode;
+    /** Assistant text reply. Chat-mode runs answer here instead of in `data`. */
+    message?: string;
+    suggestions?: AgentSuggestion[];
+    pendingApproval?: PendingApproval;
+    exchange?: AgentExchangeSummary;
+}
+/** A single run of a thread, as returned by getAgentThread. */
+interface AgentThreadRun {
+    id: string;
+    turn: number;
+    mode: AgentMode;
+    prompt: string;
+    urls?: string[];
+    schema?: unknown;
+    effort?: "low" | "medium" | "high";
+    status: "processing" | "succeeded" | "failed" | "cancelled" | "refused" | "credit_limit_reached";
+    createdAt: string;
+    finishedAt: string | null;
+    creditsUsed: number | null;
+    message: string | null;
+    /** Only present when the request asked for includeData. */
+    data?: unknown;
+    suggestions?: AgentSuggestion[] | null;
+    pendingApproval?: PendingApproval | null;
+    exchange?: AgentExchangeSummary | null;
+}
+interface AgentThread {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    status: "idle" | "running";
+    runs: AgentThreadRun[];
+}
+interface AgentThreadResponse {
+    success: boolean;
+    thread?: AgentThread;
+    error?: string;
 }
 /** Reasoning effort for agent jobs. Every level runs spark-2. */
 type AgentEffort = "low" | "medium" | "high";
@@ -1505,7 +1603,14 @@ interface SimilarPapersResponse {
     /** Human-readable note when no results are produced. */
     note?: string | null;
 }
-/** Component scores; each field is present only when that signal contributed. */
+/**
+ * Component scores; each field is present only when that signal contributed.
+ *
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. The developer index does not
+ * expose a score breakdown. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface GitHubScoreBreakdown {
     rrf?: number;
     semantic?: number;
@@ -1513,6 +1618,11 @@ interface GitHubScoreBreakdown {
     fusion?: number;
     rerank?: number;
 }
+/**
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface GitHubSearchItem {
     resultType?: "github_history" | "repo_readme" | "web";
     /** `owner/name`; empty for web results whose URL is not a repo page. */
@@ -1534,9 +1644,18 @@ interface GitHubSearchItem {
     contentMd?: string;
     scores: GitHubScoreBreakdown;
 }
+/**
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface GitHubSearchResponse {
     success: boolean;
     results: GitHubSearchItem[];
+    /** Deprecation notice while the sunset window is live. */
+    warnings?: string[];
+    /** Replacement endpoint path, while the sunset window is live. */
+    replacement?: string;
 }
 /** Options for `research.searchPapers`. */
 interface SearchPapersOptions {
@@ -1571,7 +1690,13 @@ interface SimilarPapersOptions {
     /** Additional seed paper reference(s), same format as `id`. */
     anchor?: string[];
 }
-/** Options for `research.searchGithub`. */
+/**
+ * Options for `research.searchGithub`.
+ *
+ * @deprecated Use the developer index instead. The research index GitHub
+ * search stops responding after 2026-11-03. See
+ * https://docs.firecrawl.dev/features/developer.
+ */
 interface SearchGithubOptions {
     /** Number of results to return (1–100, default 20). */
     k?: number;
@@ -1666,6 +1791,9 @@ declare function prepareAgentPayload(args: {
     webhook?: string | AgentWebhookConfig;
     threatProtection?: ThreatProtectionOptions;
     auditMetadata?: AuditMetadata$1;
+    threadId?: string;
+    mode?: AgentMode;
+    exchange?: AgentExchangeOptions;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -1756,7 +1884,16 @@ declare class ResearchClient {
      */
     similarPapers(id: string, options: SimilarPapersOptions): Promise<SimilarPapersResponse>;
     /**
-     * Search GitHub issue/PR history and repository readmes.
+     * Search the research index GitHub slice: issue/PR history and repository
+     * readmes.
+     *
+     * @deprecated Use `developerSearch()` on the client instead. This
+     * endpoint stops responding after 2026-11-03. The developer index searches
+     * GitHub issues, pull requests and readmes plus curated documentation
+     * sources, returns matched passages, and adds filters for repo, language,
+     * license and stars. It does not carry over the `scores` breakdown or the
+     * `resultType: "web"` fallback results. See
+     * https://docs.firecrawl.dev/features/developer.
      * @param query Search query.
      * @param options Optional `k`.
      */
@@ -1903,6 +2040,9 @@ declare class FirecrawlClient {
      * Access the v2 research endpoints — Firecrawl's **research paper index**
      * (~43M paper abstracts) plus GitHub history/readmes.
      *
+     * `research.searchGithub()` is deprecated and stops responding after
+     * 2026-11-03. Use `developerSearch()` instead.
+     *
      * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
      * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
      * computer science.
@@ -2105,6 +2245,14 @@ declare class FirecrawlClient {
      * @param snapshotId Snapshot id from an artifact.updated trace event.
      */
     getAgentSnapshot(jobId: string, snapshotId: string): Promise<AgentSnapshotResponse>;
+    /**
+     * Get a thread and its runs, oldest turn first.
+     * @param threadId Thread id, as returned by startAgent or getAgentStatus.
+     * @param options.includeData Inline each succeeded run's data.
+     */
+    getAgentThread(threadId: string, options?: {
+        includeData?: boolean;
+    }): Promise<AgentThreadResponse>;
     /**
      * Create a new browser session.
      * @param args Session options (ttl, activityTtl, streamWebView, profile).
@@ -3107,4 +3255,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, 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 DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, 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 MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, 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 PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, 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 ThreatProtectionOptions, 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 AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentThread, type AgentThreadResponse, type AgentThreadRun, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, 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 DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, 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 MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, 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 PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, 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 ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };