@mendable/firecrawl-js 4.16.0 → 4.17.0

package/README.md

@@ -110,6 +110,28 @@ const mapResult = await app.map('https://example.com');
 console.log(mapResult);
 ```
 
+### Scrape-bound interactive browsing (v2)
+
+Use a scrape job ID to keep interacting with the replayed browser context:
+
+```js
+const doc = await app.scrape('https://example.com', {
+  actions: [{ type: 'click', selector: 'a[href="/pricing"]' }],
+});
+
+const scrapeJobId = doc?.metadata?.scrapeId;
+if (!scrapeJobId) throw new Error('Missing scrapeId');
+
+const run = await app.interact(scrapeJobId, {
+  code: 'console.log(await page.url())',
+  language: 'node',
+  timeout: 60,
+});
+console.log(run.stdout);
+
+await app.stopInteraction(scrapeJobId);
+```
+
 ### Crawl a website with real‑time updates
 
 To receive real‑time updates, start a crawl and attach a watcher.

package/dist/{chunk-OM7BT4QE.js → chunk-2UJCMTR4.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.16.0",
+      version: "4.17.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -35,7 +35,7 @@ var require_package = __commonJS({
       license: "MIT",
       dependencies: {
         axios: "^1.13.5",
-        firecrawl: "4.15.2",
+        firecrawl: "4.16.0",
         "typescript-event-target": "^1.1.1",
         zod: "^3.23.8",
         "zod-to-json-schema": "^3.23.0"

package/dist/index.cjs

@@ -35,7 +35,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.16.0",
+      version: "4.17.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -62,7 +62,7 @@ var require_package = __commonJS({
       license: "MIT",
       dependencies: {
         axios: "^1.13.5",
-        firecrawl: "4.15.2",
+        firecrawl: "4.16.0",
         "typescript-event-target": "^1.1.1",
         zod: "^3.23.8",
         "zod-to-json-schema": "^3.23.0"
@@ -408,6 +408,48 @@ async function scrape(http, url, options) {
     throw err;
   }
 }
+async function interact(http, jobId, args) {
+  if (!jobId || !jobId.trim()) {
+    throw new Error("Job ID cannot be empty");
+  }
+  const hasCode = args?.code && args.code.trim();
+  const hasPrompt = args?.prompt && args.prompt.trim();
+  if (!hasCode && !hasPrompt) {
+    throw new Error("Either 'code' or 'prompt' must be provided");
+  }
+  const body = {};
+  if (hasCode) body.code = args.code;
+  if (hasPrompt) body.prompt = args.prompt;
+  body.language = args.language ?? "node";
+  if (args.timeout != null) body.timeout = args.timeout;
+  if (args.origin) body.origin = args.origin;
+  try {
+    const res = await http.post(
+      `/v2/scrape/${jobId}/interact`,
+      body
+    );
+    if (res.status !== 200) throwForBadResponse(res, "interact with scrape browser");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "interact with scrape browser");
+    throw err;
+  }
+}
+async function stopInteraction(http, jobId) {
+  if (!jobId || !jobId.trim()) {
+    throw new Error("Job ID cannot be empty");
+  }
+  try {
+    const res = await http.delete(
+      `/v2/scrape/${jobId}/interact`
+    );
+    if (res.status !== 200) throwForBadResponse(res, "stop interaction");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "stop interaction");
+    throw err;
+  }
+}
 
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
@@ -1322,6 +1364,40 @@ var FirecrawlClient = class {
   async scrape(url, options) {
     return scrape(this.http, url, options);
   }
+  /**
+   * Interact with the browser session associated with a scrape job.
+   * @param jobId Scrape job id.
+   * @param args Code or prompt to execute, with language/timeout options.
+   * @returns Execution result including output, stdout, stderr, exitCode, and killed status.
+   */
+  async interact(jobId, args) {
+    return interact(this.http, jobId, args);
+  }
+  /**
+   * Stop the interaction session associated with a scrape job.
+   * @param jobId Scrape job id.
+   */
+  async stopInteraction(jobId) {
+    return stopInteraction(this.http, jobId);
+  }
+  /**
+   * @deprecated Use interact().
+   */
+  async scrapeExecute(jobId, args) {
+    return this.interact(jobId, args);
+  }
+  /**
+   * @deprecated Use stopInteraction().
+   */
+  async stopInteractiveBrowser(jobId) {
+    return this.stopInteraction(jobId);
+  }
+  /**
+   * @deprecated Use stopInteraction().
+   */
+  async deleteScrapeBrowser(jobId) {
+    return this.stopInteraction(jobId);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.

package/dist/index.d.cts

@@ -119,6 +119,10 @@ interface ScrapeOptions {
     maxAge?: number;
     minAge?: number;
     storeInCache?: boolean;
+    profile?: {
+        name: string;
+        saveChanges?: boolean;
+    };
     integration?: string;
     origin?: string;
 }
@@ -578,6 +582,9 @@ interface BrowserCreateResponse {
 }
 interface BrowserExecuteResponse {
     success: boolean;
+    liveViewUrl?: string;
+    interactiveLiveViewUrl?: string;
+    output?: string;
     stdout?: string;
     result?: string;
     stderr?: string;
@@ -591,6 +598,15 @@ interface BrowserDeleteResponse {
     creditsBilled?: number;
     error?: string;
 }
+interface ScrapeExecuteRequest {
+    code?: string;
+    prompt?: string;
+    language?: "python" | "node" | "bash";
+    timeout?: number;
+    origin?: string;
+}
+type ScrapeExecuteResponse = BrowserExecuteResponse;
+type ScrapeBrowserDeleteResponse = BrowserDeleteResponse;
 interface BrowserSession {
     id: string;
     status: string;
@@ -753,6 +769,30 @@ declare class FirecrawlClient {
         json?: InferredJsonFromOptions<Opts>;
     }>;
     scrape(url: string, options?: ScrapeOptions): Promise<Document>;
+    /**
+     * Interact with the browser session associated with a scrape job.
+     * @param jobId Scrape job id.
+     * @param args Code or prompt to execute, with language/timeout options.
+     * @returns Execution result including output, stdout, stderr, exitCode, and killed status.
+     */
+    interact(jobId: string, args: ScrapeExecuteRequest): Promise<ScrapeExecuteResponse>;
+    /**
+     * Stop the interaction session associated with a scrape job.
+     * @param jobId Scrape job id.
+     */
+    stopInteraction(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
+    /**
+     * @deprecated Use interact().
+     */
+    scrapeExecute(jobId: string, args: ScrapeExecuteRequest): Promise<ScrapeExecuteResponse>;
+    /**
+     * @deprecated Use stopInteraction().
+     */
+    stopInteractiveBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
+    /**
+     * @deprecated Use stopInteraction().
+     */
+    deleteScrapeBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
     /**
      * Search the web and optionally scrape each result.
      * @param query Search query string.
@@ -1849,4 +1889,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueryFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueryFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts

@@ -119,6 +119,10 @@ interface ScrapeOptions {
     maxAge?: number;
     minAge?: number;
     storeInCache?: boolean;
+    profile?: {
+        name: string;
+        saveChanges?: boolean;
+    };
     integration?: string;
     origin?: string;
 }
@@ -578,6 +582,9 @@ interface BrowserCreateResponse {
 }
 interface BrowserExecuteResponse {
     success: boolean;
+    liveViewUrl?: string;
+    interactiveLiveViewUrl?: string;
+    output?: string;
     stdout?: string;
     result?: string;
     stderr?: string;
@@ -591,6 +598,15 @@ interface BrowserDeleteResponse {
     creditsBilled?: number;
     error?: string;
 }
+interface ScrapeExecuteRequest {
+    code?: string;
+    prompt?: string;
+    language?: "python" | "node" | "bash";
+    timeout?: number;
+    origin?: string;
+}
+type ScrapeExecuteResponse = BrowserExecuteResponse;
+type ScrapeBrowserDeleteResponse = BrowserDeleteResponse;
 interface BrowserSession {
     id: string;
     status: string;
@@ -753,6 +769,30 @@ declare class FirecrawlClient {
         json?: InferredJsonFromOptions<Opts>;
     }>;
     scrape(url: string, options?: ScrapeOptions): Promise<Document>;
+    /**
+     * Interact with the browser session associated with a scrape job.
+     * @param jobId Scrape job id.
+     * @param args Code or prompt to execute, with language/timeout options.
+     * @returns Execution result including output, stdout, stderr, exitCode, and killed status.
+     */
+    interact(jobId: string, args: ScrapeExecuteRequest): Promise<ScrapeExecuteResponse>;
+    /**
+     * Stop the interaction session associated with a scrape job.
+     * @param jobId Scrape job id.
+     */
+    stopInteraction(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
+    /**
+     * @deprecated Use interact().
+     */
+    scrapeExecute(jobId: string, args: ScrapeExecuteRequest): Promise<ScrapeExecuteResponse>;
+    /**
+     * @deprecated Use stopInteraction().
+     */
+    stopInteractiveBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
+    /**
+     * @deprecated Use stopInteraction().
+     */
+    deleteScrapeBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
     /**
      * Search the web and optionally scrape each result.
      * @param query Search query string.
@@ -1849,4 +1889,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueryFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueryFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-OM7BT4QE.js";
+} from "./chunk-2UJCMTR4.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -289,6 +289,48 @@ async function scrape(http, url, options) {
     throw err;
   }
 }
+async function interact(http, jobId, args) {
+  if (!jobId || !jobId.trim()) {
+    throw new Error("Job ID cannot be empty");
+  }
+  const hasCode = args?.code && args.code.trim();
+  const hasPrompt = args?.prompt && args.prompt.trim();
+  if (!hasCode && !hasPrompt) {
+    throw new Error("Either 'code' or 'prompt' must be provided");
+  }
+  const body = {};
+  if (hasCode) body.code = args.code;
+  if (hasPrompt) body.prompt = args.prompt;
+  body.language = args.language ?? "node";
+  if (args.timeout != null) body.timeout = args.timeout;
+  if (args.origin) body.origin = args.origin;
+  try {
+    const res = await http.post(
+      `/v2/scrape/${jobId}/interact`,
+      body
+    );
+    if (res.status !== 200) throwForBadResponse(res, "interact with scrape browser");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "interact with scrape browser");
+    throw err;
+  }
+}
+async function stopInteraction(http, jobId) {
+  if (!jobId || !jobId.trim()) {
+    throw new Error("Job ID cannot be empty");
+  }
+  try {
+    const res = await http.delete(
+      `/v2/scrape/${jobId}/interact`
+    );
+    if (res.status !== 200) throwForBadResponse(res, "stop interaction");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "stop interaction");
+    throw err;
+  }
+}
 
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
@@ -1203,6 +1245,40 @@ var FirecrawlClient = class {
   async scrape(url, options) {
     return scrape(this.http, url, options);
   }
+  /**
+   * Interact with the browser session associated with a scrape job.
+   * @param jobId Scrape job id.
+   * @param args Code or prompt to execute, with language/timeout options.
+   * @returns Execution result including output, stdout, stderr, exitCode, and killed status.
+   */
+  async interact(jobId, args) {
+    return interact(this.http, jobId, args);
+  }
+  /**
+   * Stop the interaction session associated with a scrape job.
+   * @param jobId Scrape job id.
+   */
+  async stopInteraction(jobId) {
+    return stopInteraction(this.http, jobId);
+  }
+  /**
+   * @deprecated Use interact().
+   */
+  async scrapeExecute(jobId, args) {
+    return this.interact(jobId, args);
+  }
+  /**
+   * @deprecated Use stopInteraction().
+   */
+  async stopInteractiveBrowser(jobId) {
+    return this.stopInteraction(jobId);
+  }
+  /**
+   * @deprecated Use stopInteraction().
+   */
+  async deleteScrapeBrowser(jobId) {
+    return this.stopInteraction(jobId);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.
@@ -1483,7 +1559,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-KOMYCNXX.js");
+      const packageJson = await import("./package-UDBWBSIB.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-KOMYCNXX.js → package-UDBWBSIB.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   "license": "MIT",
   "dependencies": {
     "axios": "^1.13.5",
-    "firecrawl": "4.15.2",
+    "firecrawl": "4.16.0",
     "typescript-event-target": "^1.1.1",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.0"

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

@@ -0,0 +1,104 @@
+import { describe, test, expect, jest } from "@jest/globals";
+import { interact, stopInteraction } from "../../../v2/methods/scrape";
+import { SdkError } from "../../../v2/types";
+
+describe("JS SDK v2 scrape-browser methods", () => {
+  test("interact posts to scrape interact endpoint", async () => {
+    const post = jest.fn(async () => ({
+      status: 200,
+      data: {
+        success: true,
+        stdout: "ok",
+        exitCode: 0,
+      },
+    }));
+
+    const http = { post } as any;
+    const response = await interact(http, "job-123", { code: "console.log('ok')" });
+
+    expect(post).toHaveBeenCalledWith("/v2/scrape/job-123/interact", {
+      code: "console.log('ok')",
+      language: "node",
+    });
+    expect(response.success).toBe(true);
+    expect(response.exitCode).toBe(0);
+  });
+
+  test("interact with prompt posts prompt to endpoint", async () => {
+    const post = jest.fn(async () => ({
+      status: 200,
+      data: {
+        success: true,
+        output: "Clicked the button",
+        liveViewUrl: "https://live.example.com/view",
+        interactiveLiveViewUrl: "https://live.example.com/interactive",
+        stdout: "",
+        exitCode: 0,
+      },
+    }));
+
+    const http = { post } as any;
+    const response = await interact(http, "job-456", { prompt: "Click the login button" });
+
+    expect(post).toHaveBeenCalledWith("/v2/scrape/job-456/interact", {
+      prompt: "Click the login button",
+      language: "node",
+    });
+    expect(response.success).toBe(true);
+    expect(response.output).toBe("Clicked the button");
+    expect(response.liveViewUrl).toBe("https://live.example.com/view");
+    expect(response.interactiveLiveViewUrl).toBe("https://live.example.com/interactive");
+  });
+
+  test("interact throws when neither code nor prompt provided", async () => {
+    const http = { post: jest.fn() } as any;
+    await expect(interact(http, "job-123", {})).rejects.toThrow(
+      "Either 'code' or 'prompt' must be provided"
+    );
+  });
+
+  test("interact throws on non-200 response", async () => {
+    const post = jest.fn(async () => ({
+      status: 400,
+      data: {
+        success: false,
+        error: "Invalid job ID format",
+      },
+    }));
+
+    const http = { post } as any;
+    await expect(
+      interact(http, "bad-id", { code: "console.log('ok')" })
+    ).rejects.toBeInstanceOf(SdkError);
+  });
+
+  test("stopInteraction calls delete endpoint", async () => {
+    const del = jest.fn(async () => ({
+      status: 200,
+      data: {
+        success: true,
+      },
+    }));
+
+    const http = { delete: del } as any;
+    const response = await stopInteraction(http, "job-123");
+
+    expect(del).toHaveBeenCalledWith("/v2/scrape/job-123/interact");
+    expect(response.success).toBe(true);
+  });
+
+  test("stopInteraction throws on non-200 response", async () => {
+    const del = jest.fn(async () => ({
+      status: 404,
+      data: {
+        success: false,
+        error: "Browser session not found.",
+      },
+    }));
+
+    const http = { delete: del } as any;
+    await expect(stopInteraction(http, "job-123")).rejects.toBeInstanceOf(
+      SdkError
+    );
+  });
+});

package/src/v2/client.ts

@@ -1,5 +1,9 @@
 import { HttpClient } from "./utils/httpClient";
-import { scrape } from "./methods/scrape";
+import {
+  scrape,
+  interact as interactMethod,
+  stopInteraction as stopInteractionMethod,
+} from "./methods/scrape";
 import { search } from "./methods/search";
 import { map as mapMethod } from "./methods/map";
 import {
@@ -50,6 +54,9 @@ import type {
   BrowserExecuteResponse,
   BrowserDeleteResponse,
   BrowserListResponse,
+  ScrapeExecuteRequest,
+  ScrapeExecuteResponse,
+  ScrapeBrowserDeleteResponse,
 } from "./types";
 import { Watcher } from "./watcher";
 import type { WatcherOptions } from "./watcher";
@@ -129,6 +136,46 @@ export class FirecrawlClient {
   async scrape(url: string, options?: ScrapeOptions): Promise<Document> {
     return scrape(this.http, url, options);
   }
+  /**
+   * Interact with the browser session associated with a scrape job.
+   * @param jobId Scrape job id.
+   * @param args Code or prompt to execute, with language/timeout options.
+   * @returns Execution result including output, stdout, stderr, exitCode, and killed status.
+   */
+  async interact(
+    jobId: string,
+    args: ScrapeExecuteRequest
+  ): Promise<ScrapeExecuteResponse> {
+    return interactMethod(this.http, jobId, args);
+  }
+  /**
+   * Stop the interaction session associated with a scrape job.
+   * @param jobId Scrape job id.
+   */
+  async stopInteraction(jobId: string): Promise<ScrapeBrowserDeleteResponse> {
+    return stopInteractionMethod(this.http, jobId);
+  }
+  /**
+   * @deprecated Use interact().
+   */
+  async scrapeExecute(
+    jobId: string,
+    args: ScrapeExecuteRequest
+  ): Promise<ScrapeExecuteResponse> {
+    return this.interact(jobId, args);
+  }
+  /**
+   * @deprecated Use stopInteraction().
+   */
+  async stopInteractiveBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse> {
+    return this.stopInteraction(jobId);
+  }
+  /**
+   * @deprecated Use stopInteraction().
+   */
+  async deleteScrapeBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse> {
+    return this.stopInteraction(jobId);
+  }
 
   // Search
   /**

package/src/v2/methods/scrape.ts

@@ -1,4 +1,10 @@
-import { type Document, type ScrapeOptions } from "../types";
+import {
+  type Document,
+  type ScrapeBrowserDeleteResponse,
+  type ScrapeExecuteRequest,
+  type ScrapeExecuteResponse,
+  type ScrapeOptions,
+} from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { ensureValidScrapeOptions } from "../utils/validation";
 import { throwForBadResponse, normalizeAxiosError } from "../utils/errorHandler";
@@ -24,3 +30,82 @@ export async function scrape(http: HttpClient, url: string, options?: ScrapeOpti
   }
 }
 
+export async function interact(
+  http: HttpClient,
+  jobId: string,
+  args: ScrapeExecuteRequest
+): Promise<ScrapeExecuteResponse> {
+  if (!jobId || !jobId.trim()) {
+    throw new Error("Job ID cannot be empty");
+  }
+  const hasCode = args?.code && args.code.trim();
+  const hasPrompt = args?.prompt && args.prompt.trim();
+  if (!hasCode && !hasPrompt) {
+    throw new Error("Either 'code' or 'prompt' must be provided");
+  }
+
+  const body: Record<string, unknown> = {};
+  if (hasCode) body.code = args.code;
+  if (hasPrompt) body.prompt = args.prompt;
+  body.language = args.language ?? "node";
+  if (args.timeout != null) body.timeout = args.timeout;
+  if (args.origin) body.origin = args.origin;
+
+  try {
+    const res = await http.post<ScrapeExecuteResponse>(
+      `/v2/scrape/${jobId}/interact`,
+      body
+    );
+    if (res.status !== 200) throwForBadResponse(res, "interact with scrape browser");
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "interact with scrape browser");
+    throw err;
+  }
+}
+
+export async function stopInteraction(
+  http: HttpClient,
+  jobId: string
+): Promise<ScrapeBrowserDeleteResponse> {
+  if (!jobId || !jobId.trim()) {
+    throw new Error("Job ID cannot be empty");
+  }
+
+  try {
+    const res = await http.delete<ScrapeBrowserDeleteResponse>(
+      `/v2/scrape/${jobId}/interact`
+    );
+    if (res.status !== 200) throwForBadResponse(res, "stop interaction");
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "stop interaction");
+    throw err;
+  }
+}
+
+/** @deprecated Use interact(). */
+export async function scrapeExecute(
+  http: HttpClient,
+  jobId: string,
+  args: ScrapeExecuteRequest
+): Promise<ScrapeExecuteResponse> {
+  return interact(http, jobId, args);
+}
+
+/** @deprecated Use stopInteraction(). */
+export async function stopInteractiveBrowser(
+  http: HttpClient,
+  jobId: string
+): Promise<ScrapeBrowserDeleteResponse> {
+  return stopInteraction(http, jobId);
+}
+
+/** @deprecated Use stopInteraction(). */
+export async function deleteScrapeBrowser(
+  http: HttpClient,
+  jobId: string
+): Promise<ScrapeBrowserDeleteResponse> {
+  return stopInteraction(http, jobId);
+}
+

package/src/v2/types.ts

@@ -163,6 +163,10 @@ export interface ScrapeOptions {
   maxAge?: number;
   minAge?: number;
   storeInCache?: boolean;
+  profile?: {
+    name: string;
+    saveChanges?: boolean;
+  };
   integration?: string;
   origin?: string;
 }
@@ -711,6 +715,9 @@ export interface BrowserCreateResponse {
 
 export interface BrowserExecuteResponse {
   success: boolean;
+  liveViewUrl?: string;
+  interactiveLiveViewUrl?: string;
+  output?: string;
   stdout?: string;
   result?: string;
   stderr?: string;
@@ -726,6 +733,17 @@ export interface BrowserDeleteResponse {
   error?: string;
 }
 
+export interface ScrapeExecuteRequest {
+  code?: string;
+  prompt?: string;
+  language?: "python" | "node" | "bash";
+  timeout?: number;
+  origin?: string;
+}
+
+export type ScrapeExecuteResponse = BrowserExecuteResponse;
+export type ScrapeBrowserDeleteResponse = BrowserDeleteResponse;
+
 export interface BrowserSession {
   id: string;
   status: string;