@mendable/firecrawl-js 4.39.0 → 4.41.0

package/dist/index.d.ts

@@ -118,6 +118,15 @@ type ActionOption = WaitAction | ScreenshotAction | ClickAction | WriteAction |
 interface AuditMetadata$1 {
     username: string;
 }
+/**
+ * OCR raster images (PNG, JPEG, JPEG 2000, TIFF, GIF, BMP, WebP, AVIF) as
+ * one-page documents. Part of the default parsers list next to "pdf"; takes
+ * no options, so the string "image" is equivalent. Omit it from an explicit
+ * list to keep image URLs failing as unsupported files.
+ */
+type ImageParser = {
+    type: "image";
+};
 type PDFParser = {
     type: "pdf";
     mode?: "fast" | "auto" | "ocr";
@@ -174,7 +183,7 @@ interface ScrapeOptions {
     timeout?: number;
     waitFor?: number;
     mobile?: boolean;
-    parsers?: Array<string | PDFParser>;
+    parsers?: Array<string | PDFParser | ImageParser>;
     actions?: ActionOption[];
     location?: LocationConfig$1;
     skipTlsVerification?: boolean;
@@ -200,6 +209,10 @@ interface ScrapeOptions {
     };
     integration?: string;
     origin?: string;
+    /** Include domain-matched Alexandria tools for this URL in `tools`. Default off. */
+    domainTools?: boolean;
+    /** Summary by default; compact returns identity and description, full includes contracts. */
+    toolDetail?: "compact" | "summary" | "full";
 }
 type RedactPIIEntity = "PERSON" | "EMAIL" | "PHONE" | "LOCATION" | "FINANCIAL" | "SECRET";
 interface RedactPIIOptions {
@@ -225,8 +238,14 @@ interface RedactPIIOptions {
  * fields you provide replace the team policy's values.
  */
 interface ThreatProtectionOptions {
-    /** "off" disables scanning for this request; "normal" applies the policy. */
-    mode?: "off" | "normal";
+    /**
+     * "off" disables scanning for this request; "manual-only" enforces only the
+     * blacklist / whitelist / blocked TLDs (no provider scan, no scan fee);
+     * "normal" scans with Google Web Risk; "zscaler" classifies through your
+     * organization's Zscaler connection. Enforced teams may raise the mode per
+     * request but never lower it.
+     */
+    mode?: "off" | "manual-only" | "normal" | "zscaler";
     /** Block verdicts at or above this risk score (integer 0-100). */
     riskScoreThreshold?: number;
     /** Exact domains or globs like "*.example.com" to always block (max 1000). */
@@ -244,7 +263,7 @@ interface ParseFile {
     filename: string;
     contentType?: string;
 }
-type ParseOptions = Omit<ScrapeOptions, "formats" | "waitFor" | "mobile" | "actions" | "location" | "maxAge" | "minAge" | "storeInCache" | "lockdown" | "proxy" | "threatProtection"> & {
+type ParseOptions = Omit<ScrapeOptions, "formats" | "waitFor" | "mobile" | "actions" | "location" | "maxAge" | "minAge" | "storeInCache" | "lockdown" | "proxy" | "threatProtection" | "toolDetail"> & {
     formats?: ParseFormatOption[];
     proxy?: "basic" | "auto";
 };
@@ -549,6 +568,8 @@ interface Document {
     pages?: PdfPage[];
     /** Typed PDF layout blocks, present only when `parsers[].blocks` is true. */
     blocks?: PdfPageBlocks[];
+    /** Present when `domainTools` discovered contracts matching this URL. */
+    tools?: DiscoveredTool[];
 }
 interface PaginationConfig {
     /** When true (default), automatically follow `next` links and aggregate all documents. */
@@ -650,9 +671,122 @@ interface SearchResultImages {
     position?: number;
 }
 interface SearchData {
+    warning?: string;
     web?: Array<SearchResultWeb | Document>;
     news?: Array<SearchResultNews | Document>;
     images?: Array<SearchResultImages | Document>;
+    tools?: DiscoveredTool[];
+}
+/** A complete tool contract returned by semantic or contextual discovery. */
+interface DiscoveredTool {
+    next?: AlexandriaCall;
+    id?: string;
+    provider: string;
+    capability: string;
+    name?: string;
+    description: string;
+    creditsCost?: number;
+    perRecord?: boolean;
+    options?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        [key: string]: unknown;
+    }>;
+    requiresOneOf?: string[][];
+    response?: {
+        about?: string;
+        key?: string;
+        fields?: Array<{
+            name: string;
+            type: string;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    };
+    examples?: Partial<Record<"javascript" | "python" | "curl", string>> & Record<string, string>;
+    example?: {
+        recordedAt: string;
+        request: Record<string, unknown>;
+        response: unknown;
+    };
+    label?: string;
+    whenToUse?: string;
+    returns?: unknown;
+    discovery?: unknown;
+    attribution?: unknown;
+    matchedBy?: Array<"semantic" | "domain">;
+    matchedUrls?: string[];
+    concept?: string;
+    cohorts?: string[];
+    similarity?: number;
+}
+interface FindToolsOptions {
+    urls?: string[];
+    providers?: string[];
+    categories?: string[];
+    groups?: string[];
+    capabilities?: string[];
+    level?: "providers" | "groups" | "tools";
+    expand?: Array<"options" | "response" | "examples">;
+    limit?: number;
+    offset?: number;
+}
+interface FindToolsData {
+    level: "providers" | "groups" | "tools";
+    items: Array<{
+        id: string;
+        name: string;
+        next?: AlexandriaCall;
+        execute?: Pick<AlexandriaCall, "provider" | "capability">;
+        [key: string]: unknown;
+    }>;
+    total: number;
+    next: AlexandriaCall | null;
+}
+interface AlexandriaScrapeRequest extends AlexandriaOptions {
+    alexandria: AlexandriaCall | AlexandriaCall[];
+}
+interface AlexandriaCall {
+    provider: string;
+    capability: string;
+    options?: Record<string, unknown>;
+}
+interface AlexandriaScrapeError {
+    code: string;
+    message: string;
+    status?: number;
+    /** Present when credits were captured before the failure. */
+    chargeId?: string;
+}
+type AlexandriaScrapeResult = {
+    provider: string;
+    capability: string;
+    creditsCost: number;
+    data: unknown;
+    records?: number;
+    upstreamStatus?: number;
+    recordedAt?: string;
+    error?: undefined;
+    [key: string]: unknown;
+} | {
+    provider?: string;
+    capability?: string;
+    error: AlexandriaScrapeError;
+    [key: string]: unknown;
+};
+interface AlexandriaScrapeData {
+    scrapeId: string;
+    requestId: string;
+    alexandria: AlexandriaScrapeResult[];
+    creditsCost: number;
+}
+interface AlexandriaOptions {
+    /** Reuse this ID with the identical payload when retrying an execution. */
+    requestId?: string;
+    timeout?: number;
+    integration?: string;
+    origin?: string;
 }
 /**
  * Narrows ordinary **web search**. A category does not switch `search()` to a
@@ -681,8 +815,12 @@ interface CategoryOption {
 }
 interface SearchRequest {
     query: string;
-    sources?: Array<"web" | "news" | "images" | {
-        type: "web" | "news" | "images";
+    /** Include domain-matched tools in tools alongside semantic matches. */
+    domainTools?: boolean;
+    /** Compact by default; summary adds metadata, full includes contracts. */
+    toolDetail?: "compact" | "summary" | "full";
+    sources?: Array<"web" | "news" | "images" | "alexandria" | {
+        type: "web" | "news" | "images" | "alexandria";
     }>;
     /**
      * Narrow web search by category. See {@link CategoryOption}.
@@ -704,7 +842,7 @@ interface SearchRequest {
     timeout?: number;
     /** Generate query-relevant highlights for search results. Defaults to true. */
     highlights?: boolean;
-    scrapeOptions?: ScrapeOptions;
+    scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
     /**
      * Enterprise search options. Use `["zdr"]` for end-to-end Zero Data
      * Retention or `["anon"]` for anonymized search. Must be enabled for
@@ -732,7 +870,7 @@ interface CrawlOptions {
     delay?: number | null;
     maxConcurrency?: number | null;
     webhook?: string | WebhookConfig | null;
-    scrapeOptions?: ScrapeOptions | null;
+    scrapeOptions?: Omit<ScrapeOptions, "toolDetail"> | null;
     regexOnFullURL?: boolean;
     zeroDataRetention?: boolean;
     integration?: string;
@@ -753,7 +891,7 @@ interface CrawlJob {
     data: Document[];
 }
 interface BatchScrapeOptions {
-    options?: ScrapeOptions;
+    options?: Omit<ScrapeOptions, "toolDetail">;
     webhook?: string | WebhookConfig;
     appendToId?: string;
     ignoreInvalidURLs?: boolean;
@@ -887,14 +1025,14 @@ interface MonitorScrapeTarget {
     id?: string;
     type: "scrape";
     urls: string[];
-    scrapeOptions?: ScrapeOptions;
+    scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
 }
 interface MonitorCrawlTarget {
     id?: string;
     type: "crawl";
     url: string;
     crawlOptions?: CrawlOptions;
-    scrapeOptions?: ScrapeOptions;
+    scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
 }
 interface MonitorSearchTarget {
     id?: string;
@@ -1441,12 +1579,25 @@ interface ErrorDetails {
     details?: Record<string, unknown>;
     status?: number;
 }
+/** An out-of-band step the API requires before the request can succeed. */
+interface RequiresAction {
+    type: "accept_terms" | (string & {});
+    terms?: string;
+    version?: string;
+    url?: string;
+}
+declare function parseRequiresAction(value: unknown): RequiresAction | undefined;
 declare class SdkError extends Error {
+    requestId?: string;
     status?: number;
     code?: string;
     details?: unknown;
     jobId?: string;
-    constructor(message: string, status?: number, code?: string, details?: unknown, jobId?: string);
+    /** Present on exchange-mediated scrape failures that already captured credits. */
+    chargeId?: string;
+    /** Present when the API needs an out-of-band step first, such as accepting provider terms. */
+    requiresAction?: RequiresAction;
+    constructor(message: string, status?: number, code?: string, details?: unknown, jobId?: string, chargeId?: string, requiresAction?: RequiresAction);
 }
 declare class JobTimeoutError extends SdkError {
     timeoutSeconds: number;
@@ -1972,6 +2123,9 @@ declare class FirecrawlClient {
         json?: InferredJsonFromOptions<Opts>;
     }>;
     scrape(url: string, options?: ScrapeCallOptions): Promise<Document>;
+    scrape(request: AlexandriaScrapeRequest): Promise<AlexandriaScrapeData>;
+    /** Explore the catalogue without executing the tools it returns. */
+    findTools(options?: FindToolsOptions): Promise<FindToolsData>;
     /**
      * Interact with the browser session associated with a scrape job.
      * @param jobId Scrape job id.
@@ -3255,4 +3409,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-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 };
+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 AlexandriaCall, type AlexandriaOptions, type AlexandriaScrapeData, type AlexandriaScrapeError, type AlexandriaScrapeRequest, type AlexandriaScrapeResult, 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 DiscoveredTool, 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, type FindToolsData, type FindToolsOptions, 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, type ImageParser, 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, type RequiresAction, 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, parseRequiresAction };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-4DPCCKWG.js";
+} from "./chunk-I2DFXQYR.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -138,18 +138,35 @@ var HttpClient = class {
 };
 
 // src/v2/types.ts
+function parseRequiresAction(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const record = value;
+  if (typeof record.type !== "string") return void 0;
+  const action = { type: record.type };
+  if (typeof record.terms === "string") action.terms = record.terms;
+  if (typeof record.version === "string") action.version = record.version;
+  if (typeof record.url === "string") action.url = record.url;
+  return action;
+}
 var SdkError = class extends Error {
+  requestId;
   status;
   code;
   details;
   jobId;
-  constructor(message, status, code, details, jobId) {
+  /** Present on exchange-mediated scrape failures that already captured credits. */
+  chargeId;
+  /** Present when the API needs an out-of-band step first, such as accepting provider terms. */
+  requiresAction;
+  constructor(message, status, code, details, jobId, chargeId, requiresAction) {
     super(message);
     this.name = "FirecrawlSdkError";
     this.status = status;
     this.code = code;
     this.details = details;
     this.jobId = jobId;
+    this.chargeId = chargeId;
+    this.requiresAction = requiresAction;
   }
 };
 var JobTimeoutError = class extends SdkError {
@@ -401,14 +418,30 @@ function throwForBadResponse(resp, action) {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(msg, status, void 0, body?.details);
+  throw new SdkError(
+    msg,
+    status,
+    body?.code,
+    body?.details,
+    void 0,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction)
+  );
 }
 function normalizeAxiosError(err, action) {
   const status = err.response?.status;
   const body = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = body?.code || err.code;
-  throw new SdkError(message, status, code, body?.details ?? body);
+  throw new SdkError(
+    message,
+    status,
+    code,
+    body?.details ?? body,
+    void 0,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction)
+  );
 }
 function isRetryableError(err) {
   if (err instanceof JobTimeoutError) {
@@ -454,9 +487,10 @@ async function scrape(http, url, options, deps = {}) {
     throw new Error("URL cannot be empty");
   }
   if (options) ensureValidScrapeOptions(options);
-  const { autoResume, ...requestOptions } = options ?? {};
+  const { autoResume, domainTools, ...requestOptions } = options ?? {};
   const payload = { url: url.trim() };
   Object.assign(payload, requestOptions);
+  if (domainTools) payload.domainTools = domainTools;
   const requestTimeout = autoResume === false ? typeof options?.timeout === "number" ? { timeoutMs: options.timeout + 5e3 } : {} : {
     timeoutMs: Math.max(
       typeof options?.timeout === "number" ? options.timeout : 3e5,
@@ -613,6 +647,8 @@ function prepareSearchPayload(req) {
   const payload = {
     query: req.query
   };
+  if (req.toolDetail != null) payload.toolDetail = req.toolDetail;
+  if (req.domainTools != null) payload.domainTools = req.domainTools;
   if (req.sources) payload.sources = req.sources;
   if (req.categories) payload.categories = req.categories;
   if (req.includeDomains) payload.includeDomains = req.includeDomains;
@@ -665,10 +701,12 @@ async function search(http, request) {
     }
     const data = res.data.data || {};
     const out = {};
+    if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray(data.web);
     if (data.news) out.news = transformArray(data.news);
     if (data.images)
       out.images = transformArray(data.images);
+    if (data.tools) out.tools = data.tools;
     Object.defineProperty(out, "data", {
       get() {
         const parts = [];
@@ -676,7 +714,9 @@ async function search(http, request) {
         if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
         if (out.images?.length)
           parts.push(`.images (${out.images.length} results)`);
-        const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
+        if (out.tools?.length)
+          parts.push(`.tools (${out.tools.length} results)`);
+        const available = parts.length ? parts.join(", ") : ".web, .news, .images, or .tools";
         throw new Error(
           `SearchData has no '.data'. Results are grouped by source: ${available}`
         );
@@ -691,6 +731,101 @@ async function search(http, request) {
   }
 }
 
+// src/v2/methods/tools.ts
+var ALEXANDRIA_MAX_CALLS = 10;
+function prepareAlexandriaPayload(calls, opts) {
+  if (!Array.isArray(calls) || calls.length === 0) {
+    throw new Error("alexandria requires at least one call");
+  }
+  if (calls.length > ALEXANDRIA_MAX_CALLS) {
+    throw new Error(`alexandria accepts at most ${ALEXANDRIA_MAX_CALLS} calls`);
+  }
+  const alexandria = calls.map((call, index) => {
+    if (!call || typeof call.provider !== "string" || !call.provider.trim()) {
+      throw new Error(`alexandria[${index}].provider cannot be empty`);
+    }
+    if (typeof call.capability !== "string" || !call.capability.trim()) {
+      throw new Error(`alexandria[${index}].capability cannot be empty`);
+    }
+    if (Object.keys(call).some(
+      (key) => !["provider", "capability", "options"].includes(key)
+    ))
+      throw new Error("Unknown alexandria call option");
+    const item = {
+      provider: call.provider.trim(),
+      capability: call.capability.trim()
+    };
+    if (call.options != null) {
+      if (typeof call.options !== "object" || Array.isArray(call.options)) {
+        throw new Error(`alexandria[${index}].options must be an object`);
+      }
+      item.options = call.options;
+    }
+    return item;
+  });
+  if (opts.timeout != null && (!Number.isInteger(opts.timeout) || opts.timeout <= 0)) {
+    throw new Error("timeout must be a positive integer");
+  }
+  const payload = { alexandria };
+  if (opts.timeout != null) payload.timeout = opts.timeout;
+  if (opts.integration && opts.integration.trim())
+    payload.integration = opts.integration.trim();
+  if (opts.origin) payload.origin = opts.origin;
+  return payload;
+}
+async function scrapeAlexandria(http, calls, opts = {}) {
+  const payload = prepareAlexandriaPayload(calls, opts);
+  const requestId = opts.requestId ?? crypto.randomUUID();
+  if (!/^[A-Za-z0-9._:-]{1,128}$/.test(requestId))
+    throw new Error("Invalid requestId");
+  try {
+    const res = await http.post("/v2/scrape", payload, {
+      headers: { "x-request-id": requestId },
+      // Allow response delivery after the API's capped execution deadline.
+      timeoutMs: Math.min(opts.timeout ?? 5e4, 5e4) + 3e4
+    });
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "alexandria");
+    }
+    const data = res.data.data;
+    if (!data || !Array.isArray(data.alexandria) || typeof data.creditsCost !== "number" || !Number.isInteger(data.creditsCost) || data.creditsCost < 0) {
+      throw new SdkError("Invalid alexandria response");
+    }
+    return {
+      scrapeId: res.data.scrape_id ?? "",
+      requestId,
+      alexandria: data.alexandria,
+      creditsCost: data.creditsCost
+    };
+  } catch (err) {
+    try {
+      if (err?.isAxiosError) normalizeAxiosError(err, "alexandria");
+      throw err;
+    } catch (error) {
+      if (error && typeof error === "object")
+        Object.assign(error, { requestId });
+      throw error;
+    }
+  }
+}
+async function findTools(http, options = {}) {
+  const result = await scrapeAlexandria(http, [
+    {
+      provider: "firecrawl",
+      capability: "find-tools",
+      options: { ...options }
+    }
+  ]);
+  const item = result.alexandria[0];
+  if (!item) throw new SdkError("Missing Find Tools result");
+  if (item.error)
+    throw Object.assign(
+      new SdkError(item.error.message, item.error.status, item.error.code),
+      { requestId: result.requestId }
+    );
+  return item.data;
+}
+
 // src/v2/methods/developer.ts
 var ENDPOINT = "/v2/search/developer";
 async function developerSearch(http, query, options = {}) {
@@ -1181,7 +1316,8 @@ function prepareExtractPayload(args) {
     body.threatProtection = args.threatProtection;
   if (args.scrapeOptions) {
     ensureValidScrapeOptions(args.scrapeOptions);
-    body.scrapeOptions = args.scrapeOptions;
+    const { toolDetail, domainTools, ...scrapeOptions } = args.scrapeOptions;
+    body.scrapeOptions = scrapeOptions;
   }
   return body;
 }
@@ -2018,7 +2154,28 @@ var FirecrawlClient = class {
     });
   }
   async scrape(url, options) {
-    return scrape(this.http, url, options);
+    if (typeof url === "string") return scrape(this.http, url, options);
+    if (!url || options !== void 0 || Object.keys(url).some(
+      (key) => ![
+        "alexandria",
+        "requestId",
+        "timeout",
+        "integration",
+        "origin"
+      ].includes(key)
+    )) {
+      throw new Error("Provide an alexandria request without URL scrape options");
+    }
+    const { alexandria, ...opts } = url;
+    return scrapeAlexandria(
+      this.http,
+      Array.isArray(alexandria) ? alexandria : [alexandria],
+      opts
+    );
+  }
+  /** Explore the catalogue without executing the tools it returns. */
+  async findTools(options) {
+    return findTools(this.http, options);
   }
   /**
    * Interact with the browser session associated with a scrape job.
@@ -2510,7 +2667,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-D2QZMRW7.js");
+      const packageJson = await import("./package-V72LKFNW.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -3910,5 +4067,6 @@ export {
   ResearchClient,
   SdkError,
   Watcher,
-  index_default as default
+  index_default as default,
+  parseRequiresAction
 };

package/dist/{package-D2QZMRW7.js → package-V72LKFNW.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "4.39.0",
+  "version": "4.41.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/pnpm-workspace.yaml

@@ -8,8 +8,8 @@ overrides:
   "picomatch@<4.0.4": ">=4.0.4"
   handlebars: ">=4.7.9"
   "brace-expansion@>=5.0.0 <5.0.9": "5.0.9"
-  "js-yaml@>=3.0.0 <3.15.1": "3.15.1"
-  "js-yaml@>=4.0.0 <4.3.1": "4.3.1"
+  "js-yaml@>=3.0.0 <3.15.2": "3.15.2"
+  "js-yaml@>=4.0.0 <4.3.2": "4.3.2"
   "axios@>=1.0.0 <1.16.0": "1.16.1"
   "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
   "form-data@>=4.0.0 <4.0.6": "4.0.6"

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

@@ -3,6 +3,29 @@ import { startExtract } from "../../../v2/methods/extract";
 import type { WebhookConfig } from "../../../v2/types";
 
 describe("v2.extract unit", () => {
+  test("omits discovery options from extract without mutating shared options", async () => {
+    const post = jest
+      .fn()
+      .mockResolvedValue({ status: 200, data: { id: "extract-job" } });
+    const scrapeOptions = {
+      toolDetail: "compact" as const,
+      domainTools: true,
+      onlyMainContent: true,
+    };
+    await startExtract({ post } as any, {
+      urls: ["https://example.com"],
+      scrapeOptions,
+    });
+    expect(post).toHaveBeenCalledWith("/v2/extract", {
+      urls: ["https://example.com"],
+      scrapeOptions: { onlyMainContent: true },
+    });
+    expect(scrapeOptions).toEqual({
+      toolDetail: "compact",
+      domainTools: true,
+      onlyMainContent: true,
+    });
+  });
   test("startExtract forwards string webhook in request payload", async () => {
     const post = jest.fn().mockResolvedValue({
       status: 200,

package/src/__tests__/unit/v2/threat-protection.unit.test.ts

@@ -32,7 +32,17 @@ describe("v2 threatProtection request serialization", () => {
     expect(http.post).toHaveBeenCalledWith(
       "/v2/scrape",
       expect.objectContaining({ url: "https://example.com", threatProtection }),
-      {},
+      { timeoutMs: 330000 },
+    );
+  });
+
+  test("scrape sends domainTools when true", async () => {
+    const http = makeHttp({ success: true, data: {} });
+    await scrape(http, "https://example.com", { domainTools: true });
+    expect(http.post).toHaveBeenCalledWith(
+      "/v2/scrape",
+      expect.objectContaining({ url: "https://example.com", domainTools: true }),
+      expect.anything(),
     );
   });
 
@@ -121,3 +131,10 @@ describe("v2 threatProtection request serialization", () => {
     expect(body).not.toHaveProperty("threatProtection");
   });
 });
+
+
+test.each([false, undefined])("scrape omits domainTools when %s", async (domainTools) => {
+  const http = makeHttp({ success: true, data: {} });
+  await scrape(http, "https://example.com", { domainTools });
+  expect(http.post.mock.calls[0][1]).not.toHaveProperty("domainTools");
+});