@mendable/firecrawl-js 4.42.1 → 4.42.3

package/README.md

@@ -102,6 +102,13 @@ const parsed = await app.parse(
 console.log(parsed.markdown);
 ```
 
+To see which file formats `parse` accepts, call `getParseFormats`. Each entry has `format`, `kind` (for example, `document` or `image`), `extensions`, `mimeTypes`, and `available` (false when the format is not enabled on this deployment).
+
+```js
+const formats = await app.getParseFormats();
+console.log(formats.filter((f) => f.available).map((f) => f.format));
+```
+
 ### Crawling a Website
 
 To crawl a website with error handling, use the `crawl` method. It takes the starting URL and optional parameters, including limits and per‑page `scrapeOptions`.

package/dist/{chunk-YG554MNR.js → chunk-AMV6GR2H.js}

@@ -12,7 +12,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.42.1",
+      version: "4.42.3",
       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",
@@ -29,7 +29,7 @@ var require_package = __commonJS({
         "build-and-publish": "pnpm run build && pnpm publish --access public",
         "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
         test: "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
-        "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
+        "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit"
       },
       repository: {
         type: "git",
@@ -38,7 +38,7 @@ var require_package = __commonJS({
       author: "Mendable.ai",
       license: "MIT",
       dependencies: {
-        axios: "1.18.0",
+        axios: "1.20.0",
         firecrawl: "4.30.1",
         "typescript-event-target": "^1.1.1",
         zod: "^3.23.8",

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.42.1",
+      version: "4.42.3",
       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",
@@ -56,7 +56,7 @@ var require_package = __commonJS({
         "build-and-publish": "pnpm run build && pnpm publish --access public",
         "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
         test: "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
-        "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
+        "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit"
       },
       repository: {
         type: "git",
@@ -65,7 +65,7 @@ var require_package = __commonJS({
       author: "Mendable.ai",
       license: "MIT",
       dependencies: {
-        axios: "1.18.0",
+        axios: "1.20.0",
         firecrawl: "4.30.1",
         "typescript-event-target": "^1.1.1",
         zod: "^3.23.8",
@@ -786,6 +786,16 @@ async function parse(http, file, options) {
     throw err;
   }
 }
+async function getParseFormats(http) {
+  try {
+    const res = await http.get("/v2/parse/formats");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get parse formats");
+    return res.data.data?.formats ?? [];
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get parse formats");
+    throw err;
+  }
+}
 
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
@@ -2368,6 +2378,13 @@ var FirecrawlClient = class {
   async parse(file, options) {
     return parse(this.http, file, options);
   }
+  /**
+   * List the file formats the parse endpoint accepts on this deployment.
+   * @returns Formats with their kind, extensions, MIME types, and availability.
+   */
+  async getParseFormats() {
+    return getParseFormats(this.http);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.
@@ -3216,7 +3233,7 @@ var FirecrawlApp = class {
       );
       if (response.status === 200) {
         const id = response.data.id;
-        return this.monitorJobStatus(id, headers, pollInterval);
+        return this.monitorJobStatus(id, headers, pollInterval, "batch");
       } else {
         this.handleError(response, "start batch scrape job");
       }
@@ -3520,21 +3537,23 @@ var FirecrawlApp = class {
     }
   }
   /**
-   * Monitors the status of a crawl job until completion or failure.
-   * @param id - The ID of the crawl operation.
+   * Monitors the status of a crawl or batch scrape job until completion or failure.
+   * @param id - The ID of the crawl or batch scrape operation.
    * @param headers - The headers for the request.
    * @param checkInterval - Interval in seconds for job status checks.
-   * @param checkUrl - Optional URL to check the status (used for v1 API)
+   * @param jobType - Which status endpoint to poll. Defaults to `"crawl"`.
    * @returns The final job status or data.
    */
-  async monitorJobStatus(id, headers, checkInterval) {
+  async monitorJobStatus(id, headers, checkInterval, jobType = "crawl") {
+    const statusPath = jobType === "batch" ? "batch/scrape" : "crawl";
+    const jobLabel = jobType === "batch" ? "Batch scrape" : "Crawl";
     let failedTries = 0;
     let networkRetries = 0;
     const maxNetworkRetries = 3;
     while (true) {
       try {
         let statusResponse = await this.getRequest(
-          `${this.apiUrl}/v1/crawl/${id}`,
+          `${this.apiUrl}/v1/${statusPath}/${id}`,
           headers
         );
         if (statusResponse.status === 200) {
@@ -3555,7 +3574,7 @@ var FirecrawlApp = class {
               statusData.data = data;
               return statusData;
             } else {
-              throw new FirecrawlError("Crawl job completed but no data was returned", 500);
+              throw new FirecrawlError(`${jobLabel} job completed but no data was returned`, 500);
             }
           } else if (["active", "paused", "pending", "queued", "waiting", "scraping"].includes(statusData.status)) {
             checkInterval = Math.max(checkInterval, 2);
@@ -3564,14 +3583,14 @@ var FirecrawlApp = class {
             );
           } else {
             throw new FirecrawlError(
-              `Crawl job failed or was stopped. Status: ${statusData.status}`,
+              `${jobLabel} job failed or was stopped. Status: ${statusData.status}`,
               500
             );
           }
         } else {
           failedTries++;
           if (failedTries >= 3) {
-            this.handleError(statusResponse, "check crawl status");
+            this.handleError(statusResponse, `check ${jobLabel.toLowerCase()} status`);
           }
         }
       } catch (error) {

package/dist/index.d.cts

@@ -267,6 +267,17 @@ type ParseOptions = Omit<ScrapeOptions, "formats" | "waitFor" | "mobile" | "acti
     formats?: ParseFormatOption[];
     proxy?: "basic" | "auto";
 };
+/** A file format accepted by the parse endpoint. */
+interface ParseFormatInfo {
+    /** Format identifier, e.g. "pdf". */
+    format: string;
+    kind: "document" | "image" | (string & {});
+    /** File extensions including the leading dot, e.g. ".pdf". */
+    extensions: string[];
+    mimeTypes: string[];
+    /** False when the format is recognized but not enabled on this deployment. */
+    available: boolean;
+}
 interface WebhookConfig {
     url: string;
     headers?: Record<string, string>;
@@ -1409,6 +1420,11 @@ interface AgentStatusResponse {
     status: "processing" | "completed" | "failed";
     error?: string;
     data?: unknown;
+    /** Best-effort result on a failed run; never a completed `data` value. */
+    partial?: unknown;
+    /** Schema validity of `partial`, when a schema was supplied. */
+    partialSchemaValid?: boolean;
+    stopReason?: "credit_limit_reached";
     /**
      * Server-provided model name. Widened past the request-side union on
      * purpose: new models ship without an SDK release, so pinning this to known
@@ -1447,6 +1463,9 @@ interface AgentThreadRun {
     message: string | null;
     /** Only present when the request asked for includeData. */
     data?: unknown;
+    partial?: unknown;
+    partialSchemaValid?: boolean;
+    stopReason?: "credit_limit_reached";
     suggestions?: AgentSuggestion[] | null;
     pendingApproval?: PendingApproval | null;
     exchange?: AgentExchangeSummary | null;
@@ -1999,11 +2018,11 @@ declare class HttpClient {
     getTimeoutMs(): number;
     private request;
     private sleep;
-    post<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}>>;
-    postMultipart<T = any>(endpoint: string, formData: FormData, options?: RequestOptions): Promise<AxiosResponse<T, any, {}>>;
-    get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
-    delete<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
-    patch<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}>>;
+    post<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}, any>>;
+    postMultipart<T = any>(endpoint: string, formData: FormData, options?: RequestOptions): Promise<AxiosResponse<T, any, {}, any>>;
+    get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}, any>>;
+    delete<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}, any>>;
+    patch<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}, any>>;
     prepareHeaders(idempotencyKey?: string): Record<string, string>;
 }
 
@@ -2058,6 +2077,7 @@ declare function prepareAgentPayload(args: {
     origin?: string;
     maxCredits?: number;
     strictConstrainToURLs?: boolean;
+    /** Defaults to spark-2. "spark-1-pro" and "spark-1-mini" are deprecated and run spark-2. */
     model?: "spark-1-pro" | "spark-1-mini" | "spark-2";
     effort?: AgentEffort;
     webhook?: string | AgentWebhookConfig;
@@ -2284,6 +2304,11 @@ declare class FirecrawlClient {
         json?: InferredJsonFromOptions<Opts>;
     }>;
     parse(file: ParseFile, options?: ParseOptions): Promise<Document>;
+    /**
+     * List the file formats the parse endpoint accepts on this deployment.
+     * @returns Formats with their kind, extensions, MIME types, and availability.
+     */
+    getParseFormats(): Promise<ParseFormatInfo[]>;
     /**
      * Search the web and optionally scrape each result.
      * @param query Search query string.
@@ -3363,14 +3388,14 @@ declare class FirecrawlApp {
      */
     deleteRequest(url: string, headers: AxiosRequestHeaders): Promise<AxiosResponse>;
     /**
-     * Monitors the status of a crawl job until completion or failure.
-     * @param id - The ID of the crawl operation.
+     * Monitors the status of a crawl or batch scrape job until completion or failure.
+     * @param id - The ID of the crawl or batch scrape operation.
      * @param headers - The headers for the request.
      * @param checkInterval - Interval in seconds for job status checks.
-     * @param checkUrl - Optional URL to check the status (used for v1 API)
+     * @param jobType - Which status endpoint to poll. Defaults to `"crawl"`.
      * @returns The final job status or data.
      */
-    monitorJobStatus(id: string, headers: AxiosRequestHeaders, checkInterval: number): Promise<CrawlStatusResponse | ErrorResponse>;
+    monitorJobStatus(id: string, headers: AxiosRequestHeaders, checkInterval: number, jobType?: "crawl" | "batch"): Promise<CrawlStatusResponse | ErrorResponse>;
     /**
      * Determines if an error is retryable (transient network error)
      * @param error - The error to check
@@ -3532,4 +3557,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 AgentOnTermsRequired, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSkippedProvider, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentTermsGate, type AgentTermsRequiredAction, 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 PendingApprovalCall, type PendingCallsApproval, type PendingTermsApproval, 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 };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOnTermsRequired, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSkippedProvider, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentTermsGate, type AgentTermsRequiredAction, 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 ParseFormatInfo, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PendingApprovalCall, type PendingCallsApproval, type PendingTermsApproval, 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.d.ts

@@ -267,6 +267,17 @@ type ParseOptions = Omit<ScrapeOptions, "formats" | "waitFor" | "mobile" | "acti
     formats?: ParseFormatOption[];
     proxy?: "basic" | "auto";
 };
+/** A file format accepted by the parse endpoint. */
+interface ParseFormatInfo {
+    /** Format identifier, e.g. "pdf". */
+    format: string;
+    kind: "document" | "image" | (string & {});
+    /** File extensions including the leading dot, e.g. ".pdf". */
+    extensions: string[];
+    mimeTypes: string[];
+    /** False when the format is recognized but not enabled on this deployment. */
+    available: boolean;
+}
 interface WebhookConfig {
     url: string;
     headers?: Record<string, string>;
@@ -1409,6 +1420,11 @@ interface AgentStatusResponse {
     status: "processing" | "completed" | "failed";
     error?: string;
     data?: unknown;
+    /** Best-effort result on a failed run; never a completed `data` value. */
+    partial?: unknown;
+    /** Schema validity of `partial`, when a schema was supplied. */
+    partialSchemaValid?: boolean;
+    stopReason?: "credit_limit_reached";
     /**
      * Server-provided model name. Widened past the request-side union on
      * purpose: new models ship without an SDK release, so pinning this to known
@@ -1447,6 +1463,9 @@ interface AgentThreadRun {
     message: string | null;
     /** Only present when the request asked for includeData. */
     data?: unknown;
+    partial?: unknown;
+    partialSchemaValid?: boolean;
+    stopReason?: "credit_limit_reached";
     suggestions?: AgentSuggestion[] | null;
     pendingApproval?: PendingApproval | null;
     exchange?: AgentExchangeSummary | null;
@@ -1999,11 +2018,11 @@ declare class HttpClient {
     getTimeoutMs(): number;
     private request;
     private sleep;
-    post<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}>>;
-    postMultipart<T = any>(endpoint: string, formData: FormData, options?: RequestOptions): Promise<AxiosResponse<T, any, {}>>;
-    get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
-    delete<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
-    patch<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}>>;
+    post<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}, any>>;
+    postMultipart<T = any>(endpoint: string, formData: FormData, options?: RequestOptions): Promise<AxiosResponse<T, any, {}, any>>;
+    get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}, any>>;
+    delete<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}, any>>;
+    patch<T = any>(endpoint: string, body: Record<string, unknown>, options?: RequestOptions): Promise<AxiosResponse<T, any, {}, any>>;
     prepareHeaders(idempotencyKey?: string): Record<string, string>;
 }
 
@@ -2058,6 +2077,7 @@ declare function prepareAgentPayload(args: {
     origin?: string;
     maxCredits?: number;
     strictConstrainToURLs?: boolean;
+    /** Defaults to spark-2. "spark-1-pro" and "spark-1-mini" are deprecated and run spark-2. */
     model?: "spark-1-pro" | "spark-1-mini" | "spark-2";
     effort?: AgentEffort;
     webhook?: string | AgentWebhookConfig;
@@ -2284,6 +2304,11 @@ declare class FirecrawlClient {
         json?: InferredJsonFromOptions<Opts>;
     }>;
     parse(file: ParseFile, options?: ParseOptions): Promise<Document>;
+    /**
+     * List the file formats the parse endpoint accepts on this deployment.
+     * @returns Formats with their kind, extensions, MIME types, and availability.
+     */
+    getParseFormats(): Promise<ParseFormatInfo[]>;
     /**
      * Search the web and optionally scrape each result.
      * @param query Search query string.
@@ -3363,14 +3388,14 @@ declare class FirecrawlApp {
      */
     deleteRequest(url: string, headers: AxiosRequestHeaders): Promise<AxiosResponse>;
     /**
-     * Monitors the status of a crawl job until completion or failure.
-     * @param id - The ID of the crawl operation.
+     * Monitors the status of a crawl or batch scrape job until completion or failure.
+     * @param id - The ID of the crawl or batch scrape operation.
      * @param headers - The headers for the request.
      * @param checkInterval - Interval in seconds for job status checks.
-     * @param checkUrl - Optional URL to check the status (used for v1 API)
+     * @param jobType - Which status endpoint to poll. Defaults to `"crawl"`.
      * @returns The final job status or data.
      */
-    monitorJobStatus(id: string, headers: AxiosRequestHeaders, checkInterval: number): Promise<CrawlStatusResponse | ErrorResponse>;
+    monitorJobStatus(id: string, headers: AxiosRequestHeaders, checkInterval: number, jobType?: "crawl" | "batch"): Promise<CrawlStatusResponse | ErrorResponse>;
     /**
      * Determines if an error is retryable (transient network error)
      * @param error - The error to check
@@ -3532,4 +3557,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 AgentOnTermsRequired, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSkippedProvider, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentTermsGate, type AgentTermsRequiredAction, 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 PendingApprovalCall, type PendingCallsApproval, type PendingTermsApproval, 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 };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentExchangeOptions, type AgentExchangeSummary, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentMode, type AgentOnTermsRequired, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSkippedProvider, type AgentSnapshotResponse, type AgentStatusResponse, type AgentSuggestion, type AgentTermsGate, type AgentTermsRequiredAction, 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 ParseFormatInfo, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PendingApproval, type PendingApprovalCall, type PendingCallsApproval, type PendingTermsApproval, 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-YG554MNR.js";
+} from "./chunk-AMV6GR2H.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -654,6 +654,16 @@ async function parse(http, file, options) {
     throw err;
   }
 }
+async function getParseFormats(http) {
+  try {
+    const res = await http.get("/v2/parse/formats");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get parse formats");
+    return res.data.data?.formats ?? [];
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get parse formats");
+    throw err;
+  }
+}
 
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
@@ -2236,6 +2246,13 @@ var FirecrawlClient = class {
   async parse(file, options) {
     return parse(this.http, file, options);
   }
+  /**
+   * List the file formats the parse endpoint accepts on this deployment.
+   * @returns Formats with their kind, extensions, MIME types, and availability.
+   */
+  async getParseFormats() {
+    return getParseFormats(this.http);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.
@@ -2689,7 +2706,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-FOKY5K5X.js");
+      const packageJson = await import("./package-RQDQRVLO.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -3084,7 +3101,7 @@ var FirecrawlApp = class {
       );
       if (response.status === 200) {
         const id = response.data.id;
-        return this.monitorJobStatus(id, headers, pollInterval);
+        return this.monitorJobStatus(id, headers, pollInterval, "batch");
       } else {
         this.handleError(response, "start batch scrape job");
       }
@@ -3388,21 +3405,23 @@ var FirecrawlApp = class {
     }
   }
   /**
-   * Monitors the status of a crawl job until completion or failure.
-   * @param id - The ID of the crawl operation.
+   * Monitors the status of a crawl or batch scrape job until completion or failure.
+   * @param id - The ID of the crawl or batch scrape operation.
    * @param headers - The headers for the request.
    * @param checkInterval - Interval in seconds for job status checks.
-   * @param checkUrl - Optional URL to check the status (used for v1 API)
+   * @param jobType - Which status endpoint to poll. Defaults to `"crawl"`.
    * @returns The final job status or data.
    */
-  async monitorJobStatus(id, headers, checkInterval) {
+  async monitorJobStatus(id, headers, checkInterval, jobType = "crawl") {
+    const statusPath = jobType === "batch" ? "batch/scrape" : "crawl";
+    const jobLabel = jobType === "batch" ? "Batch scrape" : "Crawl";
     let failedTries = 0;
     let networkRetries = 0;
     const maxNetworkRetries = 3;
     while (true) {
       try {
         let statusResponse = await this.getRequest(
-          `${this.apiUrl}/v1/crawl/${id}`,
+          `${this.apiUrl}/v1/${statusPath}/${id}`,
           headers
         );
         if (statusResponse.status === 200) {
@@ -3423,7 +3442,7 @@ var FirecrawlApp = class {
               statusData.data = data;
               return statusData;
             } else {
-              throw new FirecrawlError("Crawl job completed but no data was returned", 500);
+              throw new FirecrawlError(`${jobLabel} job completed but no data was returned`, 500);
             }
           } else if (["active", "paused", "pending", "queued", "waiting", "scraping"].includes(statusData.status)) {
             checkInterval = Math.max(checkInterval, 2);
@@ -3432,14 +3451,14 @@ var FirecrawlApp = class {
             );
           } else {
             throw new FirecrawlError(
-              `Crawl job failed or was stopped. Status: ${statusData.status}`,
+              `${jobLabel} job failed or was stopped. Status: ${statusData.status}`,
               500
             );
           }
         } else {
           failedTries++;
           if (failedTries >= 3) {
-            this.handleError(statusResponse, "check crawl status");
+            this.handleError(statusResponse, `check ${jobLabel.toLowerCase()} status`);
           }
         }
       } catch (error) {

package/dist/{package-FOKY5K5X.js → package-RQDQRVLO.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "4.42.1",
+  "version": "4.42.3",
   "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",
@@ -19,7 +19,7 @@
   "author": "Mendable.ai",
   "license": "MIT",
   "dependencies": {
-    "axios": "1.18.0",
+    "axios": "1.20.0",
     "firecrawl": "4.30.1",
     "typescript-event-target": "^1.1.1",
     "zod": "^3.23.8",
@@ -74,6 +74,6 @@
     "build-and-publish": "pnpm run build && pnpm publish --access public",
     "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
-    "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
+    "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit"
   }
 }

package/pnpm-workspace.yaml

@@ -12,7 +12,12 @@ overrides:
   "brace-expansion@>=5.0.0 <5.0.12": "5.0.12"
   "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"
+  # GHSA-vh66-26gq-q6x8 / GHSA-9fr6-4gfg-395g / GHSA-c29m-xwm3-cm6r /
+  # GHSA-mghh-pgcx-3jjj / GHSA-x97p-jq2g-jp4f / GHSA-3pq3-5fj3-cg6v /
+  # GHSA-542g-h47m-68v8 / GHSA-j8rh-479h-cp32 / GHSA-4hqw-qxg8-jxx2 /
+  # GHSA-m8m8-qj5v-23w3 / GHSA-44g4-m2mj-wpvx / GHSA-r4gj-5m52-g5wh:
+  # pin the 1.x line only. Exact 1.20.0 cannot resolve to 2.x.
+  "axios@>=1.0.0 <1.20.0": "1.20.0"
   "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
   "form-data@>=4.0.0 <4.0.6": "4.0.6"
   "@babel/core@>=7.0.0 <7.29.6": "7.29.7"

package/src/__tests__/e2e/v2/parse.test.ts

@@ -3,6 +3,7 @@ import { config } from "dotenv";
 import { getIdentity, getApiUrl } from "./utils/idmux";
 import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
 import { describe, test, expect, beforeAll } from "@jest/globals";
+import { SdkError } from "../../../v2/types";
 
 config();
 
@@ -65,4 +66,29 @@ describe("v2.parse e2e", () => {
     },
     testTimeoutMs(60_000),
   );
+
+  test(
+    "lists supported parse formats",
+    async () => {
+      if (!client) throw new Error();
+
+      let formats;
+      try {
+        formats = await client.getParseFormats();
+      } catch (err) {
+        if (err instanceof SdkError && err.status === 404) {
+          console.warn("Skipping: /v2/parse/formats is not deployed on this API");
+          return;
+        }
+        throw err;
+      }
+
+      expect(formats.length).toBeGreaterThan(0);
+      const pdf = formats.find(f => f.format === "pdf");
+      expect(pdf?.kind).toBe("document");
+      expect(pdf?.extensions).toContain(".pdf");
+      expect(pdf?.mimeTypes).toContain("application/pdf");
+    },
+    testTimeoutMs(60_000),
+  );
 });

package/src/__tests__/unit/v1/batch-scrape-poll.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect, jest, afterEach, beforeEach } from "@jest/globals";
+import axios from "axios";
+import FirecrawlApp from "../../../v1";
+
+const API_URL = "https://api.firecrawl.dev";
+const API_KEY = "fc-test";
+
+const scrapingPage = () => ({ success: true, status: "scraping", total: 2, completed: 0, data: [] });
+const completedPage = (next: string) => ({
+  success: true,
+  status: "completed",
+  total: 2,
+  completed: 2,
+  expiresAt: "2030-01-01T00:00:00Z",
+  data: [{ markdown: "a" }],
+  next,
+});
+const lastPage = () => ({ success: true, status: "completed", data: [{ markdown: "b" }] });
+
+function mockPoll(path: string, nextOrigin = API_URL) {
+  const sent: string[] = [];
+  let polls = 0;
+  jest.spyOn(axios, "get").mockImplementation(async (url: string) => {
+    sent.push(url);
+    if (new URL(url).searchParams.has("skip")) return { status: 200, data: lastPage() };
+    polls++;
+    return { status: 200, data: polls === 1 ? scrapingPage() : completedPage(`${nextOrigin}${path}?skip=1`) };
+  });
+  return sent;
+}
+
+describe("v1 batch scrape waits on the batch scrape status endpoint", () => {
+  const app = new FirecrawlApp({ apiKey: API_KEY, apiUrl: API_URL });
+
+  beforeEach(() => {
+    jest.spyOn(global, "setTimeout").mockImplementation(((fn: () => void) => {
+      fn();
+      return 0;
+    }) as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test("batchScrapeUrls polls /v1/batch/scrape/{id} and follows pinned next pages", async () => {
+    const post = jest.spyOn(axios, "post").mockResolvedValue({ status: 200, data: { success: true, id: "abc" } });
+    const path = "/v1/batch/scrape/abc";
+    const sent = mockPoll(path, "https://evil.example");
+
+    const res: any = await app.batchScrapeUrls(["https://example.com", "https://example.org"], {});
+
+    expect(post.mock.calls[0][0]).toBe(`${API_URL}/v1/batch/scrape`);
+    expect(sent).toEqual([`${API_URL}${path}`, `${API_URL}${path}`, `${API_URL}${path}?skip=1`]);
+    expect(sent.some(url => url.includes("/v1/crawl/"))).toBe(false);
+    expect(res.status).toBe("completed");
+    expect(res.data).toHaveLength(2);
+  });
+
+  test("batchScrapeUrls reports batch scrape failures as batch scrape errors", async () => {
+    jest.spyOn(axios, "post").mockResolvedValue({ status: 200, data: { success: true, id: "abc" } });
+    const sent: string[] = [];
+    jest.spyOn(axios, "get").mockImplementation(async (url: string) => {
+      sent.push(url);
+      return { status: 200, data: { success: true, status: "failed", data: [] } };
+    });
+
+    await expect(app.batchScrapeUrls(["https://example.com"], {})).rejects.toThrow("Batch scrape job failed or was stopped");
+    expect(sent.every(url => url === `${API_URL}/v1/batch/scrape/abc`)).toBe(true);
+  });
+
+  test("monitorJobStatus still polls /v1/crawl/{id} by default", async () => {
+    const path = "/v1/crawl/abc";
+    const sent = mockPoll(path);
+
+    const res: any = await app.monitorJobStatus("abc", app.prepareHeaders(), 0);
+
+    expect(sent).toEqual([`${API_URL}${path}`, `${API_URL}${path}`, `${API_URL}${path}?skip=1`]);
+    expect(res.data).toHaveLength(2);
+  });
+
+  test("monitorJobStatus polls /v1/batch/scrape/{id} for batch jobs", async () => {
+    const path = "/v1/batch/scrape/abc";
+    const sent = mockPoll(path);
+
+    const res: any = await app.monitorJobStatus("abc", app.prepareHeaders(), 0, "batch");
+
+    expect(sent).toEqual([`${API_URL}${path}`, `${API_URL}${path}`, `${API_URL}${path}?skip=1`]);
+    expect(res.data).toHaveLength(2);
+  });
+});

package/src/__tests__/unit/v1/monitor-job-status-retry.test.ts

@@ -1,154 +1,107 @@
-import FirecrawlApp from '../../../index';
+import FirecrawlApp from '../../../v1';
 import { describe, test, expect, jest, beforeEach, afterEach } from '@jest/globals';
 
+const successResponse = {
+  status: 200,
+  data: { status: 'completed', data: [{ url: 'test.com', markdown: 'test' }] },
+};
+
+function networkError(message: string, code: string) {
+  return Object.assign(new Error(message), { code });
+}
+
+function httpError(message: string, status: number) {
+  return Object.assign(new Error(message), { response: { status, data: { error: message } } });
+}
+
 describe('monitorJobStatus retry logic', () => {
   let app: FirecrawlApp;
-  let originalConsoleWarn: typeof console.warn;
-  
+  let delays: number[];
+
   beforeEach(() => {
     app = new FirecrawlApp({ apiKey: 'test-key', apiUrl: 'https://test.com' });
-    originalConsoleWarn = console.warn;
-    console.warn = jest.fn();
+    delays = [];
+    jest.useFakeTimers();
+    const fakeSetTimeout = globalThis.setTimeout;
+    jest.spyOn(globalThis, 'setTimeout').mockImplementation(((fn: () => void, ms?: number) => {
+      delays.push(ms ?? 0);
+      return fakeSetTimeout(fn, ms);
+    }) as any);
   });
 
   afterEach(() => {
-    console.warn = originalConsoleWarn;
-    jest.clearAllMocks();
+    jest.restoreAllMocks();
+    jest.useRealTimers();
   });
 
-  test('should retry on socket hang up error', async () => {
-    const socketHangUpError = new Error('socket hang up') as any;
-    socketHangUpError.code = 'ECONNRESET';
-    
-    const successResponse = {
-      status: 200,
-      data: { status: 'completed', data: [{ url: 'test.com', markdown: 'test' }] }
-    };
-
-    const originalGetRequest = app.getRequest;
-    let callCount = 0;
-    
-    app.getRequest = async function(url: string, headers: any) {
-      callCount++;
-      if (callCount === 1) {
-        throw socketHangUpError;
-      }
-      return successResponse;
-    };
-
-    const result = await app.monitorJobStatus('test-id', {}, 1);
-    
-    expect(callCount).toBe(2);
+  function failFirst(n: number, error: Error, statuses: string[] = []) {
+    let calls = 0;
+    app.getRequest = (async () => {
+      calls++;
+      if (calls <= n) throw error;
+      const status = statuses.shift();
+      return status ? { status: 200, data: { status } } : successResponse;
+    }) as any;
+    return () => calls;
+  }
+
+  async function monitor() {
+    const result = app.monitorJobStatus('test-id', {} as any, 1);
+    result.catch(() => {});
+    await jest.runAllTimersAsync();
+    return result;
+  }
+
+  test.each([
+    ['socket hang up', networkError('socket hang up', 'ECONNRESET')],
+    ['ETIMEDOUT', networkError('timeout', 'ETIMEDOUT')],
+    ['HTTP 408', httpError('Request timeout', 408)],
+    ['HTTP 504', httpError('Gateway timeout', 504)],
+  ])('retries once after a %s error and returns the job data', async (_label, error) => {
+    const calls = failFirst(1, error);
+
+    const result = await monitor();
+
+    expect(calls()).toBe(2);
     expect(result).toEqual(successResponse.data);
-    expect(console.warn).toHaveBeenCalledWith(
-      expect.stringContaining('Network error during job status check (attempt 1/3): socket hang up')
-    );
+    expect(delays).toEqual([1000]);
   });
 
-  test('should retry on ETIMEDOUT error', async () => {
-    const timeoutError = new Error('timeout') as any;
-    timeoutError.code = 'ETIMEDOUT';
-    
-    const successResponse = {
-      status: 200,
-      data: { status: 'completed', data: [{ url: 'test.com', markdown: 'test' }] }
-    };
-
-    const originalGetRequest = app.getRequest;
-    let callCount = 0;
-    
-    app.getRequest = async function(url: string, headers: any) {
-      callCount++;
-      if (callCount === 1) {
-        throw timeoutError;
-      }
-      return successResponse;
-    };
-
-    const result = await app.monitorJobStatus('test-id', {}, 1);
-    
-    expect(callCount).toBe(2);
+  test('uses exponential backoff between retries', async () => {
+    const calls = failFirst(2, networkError('socket hang up', 'ECONNRESET'));
+
+    const result = await monitor();
+
+    expect(calls()).toBe(3);
     expect(result).toEqual(successResponse.data);
+    expect(delays).toEqual([1000, 2000]);
   });
 
-  test('should fail after max retries exceeded', async () => {
-    const socketHangUpError = new Error('socket hang up') as any;
-    socketHangUpError.code = 'ECONNRESET';
-    
-    app.getRequest = async function(url: string, headers: any) {
-      throw socketHangUpError;
-    };
-
-    await expect(app.monitorJobStatus('test-id', {}, 1)).rejects.toThrow('socket hang up');
-    
-    expect(console.warn).toHaveBeenCalledTimes(3);
-  }, 15000);
-
-  test('should not retry on non-retryable errors', async () => {
-    const authError = new Error('Unauthorized') as any;
-    authError.response = { status: 401, data: { error: 'Unauthorized' } };
-    
-    app.getRequest = async function(url: string, headers: any) {
-      throw authError;
-    };
-
-    await expect(app.monitorJobStatus('test-id', {}, 1)).rejects.toThrow('Unauthorized');
-    
-    expect(console.warn).not.toHaveBeenCalled();
-  });
+  test('records both the retry backoff and the 2s poll wait for an active job', async () => {
+    const calls = failFirst(1, networkError('socket hang up', 'ECONNRESET'), ['active']);
+
+    const result = await monitor();
 
-  test('should retry on HTTP timeout status codes', async () => {
-    const timeoutError = new Error('Request timeout') as any;
-    timeoutError.response = { status: 408, data: { error: 'Request timeout' } };
-    
-    const successResponse = {
-      status: 200,
-      data: { status: 'completed', data: [{ url: 'test.com', markdown: 'test' }] }
-    };
-
-    const originalGetRequest = app.getRequest;
-    let callCount = 0;
-    
-    app.getRequest = async function(url: string, headers: any) {
-      callCount++;
-      if (callCount === 1) {
-        throw timeoutError;
-      }
-      return successResponse;
-    };
-
-    const result = await app.monitorJobStatus('test-id', {}, 1);
-    
-    expect(callCount).toBe(2);
+    expect(calls()).toBe(3);
     expect(result).toEqual(successResponse.data);
+    expect(delays).toEqual([1000, 2000]);
   });
 
-  test('should use exponential backoff for retries', async () => {
-    const socketHangUpError = new Error('socket hang up') as any;
-    socketHangUpError.code = 'ECONNRESET';
-    
-    const successResponse = {
-      status: 200,
-      data: { status: 'completed', data: [{ url: 'test.com', markdown: 'test' }] }
-    };
-
-    const originalGetRequest = app.getRequest;
-    let callCount = 0;
-    
-    app.getRequest = async function(url: string, headers: any) {
-      callCount++;
-      if (callCount <= 2) {
-        throw socketHangUpError;
-      }
-      return successResponse;
-    };
-
-    const startTime = Date.now();
-    const result = await app.monitorJobStatus('test-id', {}, 1);
-    const endTime = Date.now();
-    
-    expect(callCount).toBe(3);
-    expect(result).toEqual(successResponse.data);
-    expect(endTime - startTime).toBeGreaterThan(3000);
+  test('fails after max retries are exceeded', async () => {
+    const calls = failFirst(Infinity, networkError('socket hang up', 'ECONNRESET'));
+
+    await expect(monitor()).rejects.toThrow('socket hang up');
+
+    expect(calls()).toBe(4);
+    expect(delays).toEqual([1000, 2000, 4000]);
+  });
+
+  test('does not retry non-retryable errors', async () => {
+    const calls = failFirst(Infinity, httpError('Unauthorized', 401));
+
+    await expect(monitor()).rejects.toThrow('Unauthorized');
+
+    expect(calls()).toBe(1);
+    expect(delays).toEqual([]);
   });
 });

package/src/__tests__/unit/v2/parse-formats.unit.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from "@jest/globals";
+import axios, { type AxiosAdapter } from "axios";
+import { Firecrawl } from "../../../index";
+import { SdkError } from "../../../v2/types";
+
+const API_URL = "https://api.firecrawl.dev";
+const API_KEY = "fc-test";
+
+function makeClient(status: number, data: unknown) {
+  const client = new Firecrawl({ apiKey: API_KEY, apiUrl: API_URL });
+  const sent: Array<{ url: string; method?: string; authorization: unknown }> = [];
+  const adapter: AxiosAdapter = async config => {
+    sent.push({ url: axios.getUri(config), method: config.method, authorization: config.headers.Authorization });
+    const response = { data, status, statusText: "", headers: {}, config };
+    if (status >= 400) {
+      throw new axios.AxiosError(`Request failed with status code ${status}`, "ERR_BAD_RESPONSE", config, null, response);
+    }
+    return response;
+  };
+  (client as any).http.instance.defaults.adapter = adapter;
+  return { client, sent };
+}
+
+describe("v2.getParseFormats unit", () => {
+  test("GETs /v2/parse/formats with auth and unwraps data.formats", async () => {
+    const { client, sent } = makeClient(200, {
+      success: true,
+      data: {
+        formats: [
+          { format: "pdf", kind: "document", extensions: [".pdf"], mimeTypes: ["application/pdf"], available: true },
+          { format: "png", kind: "image", extensions: [".png"], mimeTypes: ["image/png"], available: false },
+        ],
+      },
+    });
+
+    const formats = await client.getParseFormats();
+
+    expect(sent).toEqual([{ url: `${API_URL}/v2/parse/formats`, method: "get", authorization: `Bearer ${API_KEY}` }]);
+    expect(formats).toHaveLength(2);
+    expect(formats[0]).toEqual({ format: "pdf", kind: "document", extensions: [".pdf"], mimeTypes: ["application/pdf"], available: true });
+    expect(formats[1]!.kind).toBe("image");
+    expect(formats[1]!.mimeTypes).toEqual(["image/png"]);
+    expect(formats[1]!.available).toBe(false);
+  });
+
+  test("tolerates unknown kinds and extra fields", async () => {
+    const { client } = makeClient(200, {
+      success: true,
+      data: {
+        formats: [
+          { format: "mp3", kind: "audio", extensions: [".mp3"], mimeTypes: ["audio/mpeg"], available: true, maxSizeMb: 50 },
+        ],
+      },
+    });
+
+    const [format] = await client.getParseFormats();
+
+    expect(format!.format).toBe("mp3");
+    expect(format!.kind).toBe("audio");
+    expect(format!.mimeTypes).toEqual(["audio/mpeg"]);
+  });
+
+  test("returns an empty list when formats is missing", async () => {
+    const { client } = makeClient(200, { success: true, data: {} });
+
+    await expect(client.getParseFormats()).resolves.toEqual([]);
+  });
+
+  test.each([401, 500])("throws SdkError on %i", async status => {
+    const { client } = makeClient(status, { success: false, error: "Unauthorized" });
+
+    const err = await client.getParseFormats().catch(e => e);
+
+    expect(err).toBeInstanceOf(SdkError);
+    expect(err.status).toBe(status);
+    expect(err.message).toBe("Unauthorized");
+  });
+
+  test("throws SdkError when success is false", async () => {
+    const { client } = makeClient(200, { success: false, error: "nope" });
+
+    await expect(client.getParseFormats()).rejects.toBeInstanceOf(SdkError);
+  });
+});

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

@@ -1,11 +1,60 @@
-/**
- * Minimal unit test for v2 scrape (no mocking; sanity check payload path)
- */
+import { describe, test, expect } from "@jest/globals";
+import axios, { type AxiosAdapter } from "axios";
 import { FirecrawlClient } from "../../../v2/client";
 
+const API_URL = "https://api.firecrawl.dev";
+
+function makeClient(apiKey: string) {
+  const client = new FirecrawlClient({ apiKey, apiUrl: API_URL });
+  const sent: Array<{ method?: string; url: string; authorization: unknown; body: unknown }> = [];
+  const adapter: AxiosAdapter = async config => {
+    sent.push({
+      method: config.method,
+      url: axios.getUri(config),
+      authorization: config.headers.Authorization,
+      body: JSON.parse(config.data),
+    });
+    return {
+      data: { success: true, data: { markdown: "# hello" } },
+      status: 200,
+      statusText: "OK",
+      headers: {},
+      config,
+    };
+  };
+  (client as any).http.instance.defaults.adapter = adapter;
+  return { client, sent };
+}
+
 describe("v2.scrape unit", () => {
-  test("constructor requires apiKey", () => {
-    expect(() => new FirecrawlClient({ apiKey: "", apiUrl: "https://api.firecrawl.dev" })).toThrow();
+  test("constructs without an API key and scrapes keyless, without an Authorization header", async () => {
+    const { client, sent } = makeClient("");
+    const doc = await client.scrape(" https://example.com ", { formats: ["markdown"] });
+
+    expect(doc.markdown).toBe("# hello");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.method).toBe("post");
+    expect(sent[0]!.url).toBe(`${API_URL}/v2/scrape`);
+    expect(sent[0]!.authorization).toBeUndefined();
+    expect(sent[0]!.body).toEqual({
+      url: "https://example.com",
+      formats: ["markdown"],
+      origin: expect.stringMatching(/^js-sdk@/),
+    });
   });
-});
 
+  test("sends the API key as a bearer token when one is set", async () => {
+    const { client, sent } = makeClient("fc-test");
+    await client.scrape("https://example.com");
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.authorization).toBe("Bearer fc-test");
+  });
+
+  test("rejects an empty URL before sending a request", async () => {
+    const { client, sent } = makeClient("fc-test");
+
+    await expect(client.scrape("  ")).rejects.toThrow("URL cannot be empty");
+    expect(sent).toHaveLength(0);
+  });
+});

package/src/v1/index.ts

@@ -1128,7 +1128,7 @@ export default class FirecrawlApp {
       );
       if (response.status === 200) {
         const id: string = response.data.id;
-        return this.monitorJobStatus(id, headers, pollInterval);
+        return this.monitorJobStatus(id, headers, pollInterval, "batch");
       } else {
         this.handleError(response, "start batch scrape job");
       }
@@ -1484,18 +1484,21 @@ export default class FirecrawlApp {
   }
 
   /**
-   * Monitors the status of a crawl job until completion or failure.
-   * @param id - The ID of the crawl operation.
+   * Monitors the status of a crawl or batch scrape job until completion or failure.
+   * @param id - The ID of the crawl or batch scrape operation.
    * @param headers - The headers for the request.
    * @param checkInterval - Interval in seconds for job status checks.
-   * @param checkUrl - Optional URL to check the status (used for v1 API)
+   * @param jobType - Which status endpoint to poll. Defaults to `"crawl"`.
    * @returns The final job status or data.
    */
   async monitorJobStatus(
     id: string,
     headers: AxiosRequestHeaders,
-    checkInterval: number
+    checkInterval: number,
+    jobType: "crawl" | "batch" = "crawl"
   ): Promise<CrawlStatusResponse | ErrorResponse> {
+    const statusPath = jobType === "batch" ? "batch/scrape" : "crawl";
+    const jobLabel = jobType === "batch" ? "Batch scrape" : "Crawl";
     let failedTries = 0;
     let networkRetries = 0;
     const maxNetworkRetries = 3;
@@ -1503,7 +1506,7 @@ export default class FirecrawlApp {
     while (true) {
       try {
         let statusResponse: AxiosResponse = await this.getRequest(
-          `${this.apiUrl}/v1/crawl/${id}`,
+          `${this.apiUrl}/v1/${statusPath}/${id}`,
           headers
         );
         
@@ -1526,7 +1529,7 @@ export default class FirecrawlApp {
               statusData.data = data;
               return statusData;
             } else {
-              throw new FirecrawlError("Crawl job completed but no data was returned", 500);
+              throw new FirecrawlError(`${jobLabel} job completed but no data was returned`, 500);
             }
           } else if (
             ["active", "paused", "pending", "queued", "waiting", "scraping"].includes(statusData.status)
@@ -1537,14 +1540,14 @@ export default class FirecrawlApp {
             );
           } else {
             throw new FirecrawlError(
-              `Crawl job failed or was stopped. Status: ${statusData.status}`,
+              `${jobLabel} job failed or was stopped. Status: ${statusData.status}`,
               500
             );
           }
         } else {
           failedTries++;
           if (failedTries >= 3) {
-            this.handleError(statusResponse, "check crawl status");
+            this.handleError(statusResponse, `check ${jobLabel.toLowerCase()} status`);
           }
         }
       } catch (error: any) {

package/src/v2/client.ts

@@ -4,7 +4,7 @@ import {
   interact as interactMethod,
   stopInteraction as stopInteractionMethod,
 } from "./methods/scrape";
-import { parse as parseMethod } from "./methods/parse";
+import { parse as parseMethod, getParseFormats } from "./methods/parse";
 import { search } from "./methods/search";
 import { scrapeAlexandria, findTools } from "./methods/tools";
 import { developerSearch as developerSearchMethod } from "./methods/developer";
@@ -53,6 +53,7 @@ import type {
   FindToolsData,
   AlexandriaScrapeData,
   ParseFile,
+  ParseFormatInfo,
   ParseOptions,
   ScrapeOptions,
   SearchData,
@@ -273,6 +274,14 @@ export class FirecrawlClient {
     return parseMethod(this.http, file, options);
   }
 
+  /**
+   * List the file formats the parse endpoint accepts on this deployment.
+   * @returns Formats with their kind, extensions, MIME types, and availability.
+   */
+  async getParseFormats(): Promise<ParseFormatInfo[]> {
+    return getParseFormats(this.http);
+  }
+
   // Search
   /**
    * Search the web and optionally scrape each result.

package/src/v2/methods/agent.ts

@@ -12,6 +12,7 @@ function prepareAgentPayload(args: {
   origin?: string;
   maxCredits?: number;
   strictConstrainToURLs?: boolean;
+  /** Defaults to spark-2. "spark-1-pro" and "spark-1-mini" are deprecated and run spark-2. */
   model?: "spark-1-pro" | "spark-1-mini" | "spark-2";
   effort?: AgentEffort;
   webhook?: string | AgentWebhookConfig;

package/src/v2/methods/parse.ts

@@ -1,4 +1,4 @@
-import { type Document, type ParseFile, type ParseOptions } from "../types";
+import { type Document, type ParseFile, type ParseFormatInfo, type ParseOptions } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidParseOptions } from "../utils/validation";
@@ -95,3 +95,14 @@ export async function parse(
     throw err;
   }
 }
+
+export async function getParseFormats(http: HttpClient): Promise<ParseFormatInfo[]> {
+  try {
+    const res = await http.get<{ success: boolean; data?: { formats: ParseFormatInfo[] } }>("/v2/parse/formats");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get parse formats");
+    return res.data.data?.formats ?? [];
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get parse formats");
+    throw err;
+  }
+}

package/src/v2/types.ts

@@ -366,6 +366,18 @@ export type ParseOptions = Omit<
   proxy?: "basic" | "auto";
 };
 
+/** A file format accepted by the parse endpoint. */
+export interface ParseFormatInfo {
+  /** Format identifier, e.g. "pdf". */
+  format: string;
+  kind: "document" | "image" | (string & {});
+  /** File extensions including the leading dot, e.g. ".pdf". */
+  extensions: string[];
+  mimeTypes: string[];
+  /** False when the format is recognized but not enabled on this deployment. */
+  available: boolean;
+}
+
 export interface WebhookConfig {
   url: string;
   headers?: Record<string, string>;
@@ -1627,6 +1639,11 @@ export interface AgentStatusResponse {
   status: "processing" | "completed" | "failed";
   error?: string;
   data?: unknown;
+  /** Best-effort result on a failed run; never a completed `data` value. */
+  partial?: unknown;
+  /** Schema validity of `partial`, when a schema was supplied. */
+  partialSchemaValid?: boolean;
+  stopReason?: "credit_limit_reached";
   /**
    * Server-provided model name. Widened past the request-side union on
    * purpose: new models ship without an SDK release, so pinning this to known
@@ -1672,6 +1689,9 @@ export interface AgentThreadRun {
   message: string | null;
   /** Only present when the request asked for includeData. */
   data?: unknown;
+  partial?: unknown;
+  partialSchemaValid?: boolean;
+  stopReason?: "credit_limit_reached";
   suggestions?: AgentSuggestion[] | null;
   pendingApproval?: PendingApproval | null;
   exchange?: AgentExchangeSummary | null;