Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
Nick:
Nicolasf0aebdb7db31
diff --git a/apps/api/requests/v2/browser.requests.http b/apps/api/requests/v2/browser.requests.httpindex fbceca1a6..fe046fc92 100644--- a/apps/api/requests/v2/browser.requests.http+++ b/apps/api/requests/v2/browser.requests.http@@ -81,6 +81,23 @@ content-type: application/json"language": "python"}+### Get Session Replay metadata β works after the session is destroyed+GET {{baseUrl}}/v2/interact/{{sessionId}}/replay HTTP/1.1+Authorization: Bearer {{$dotenv TEST_API_KEY}}++### Get Session Replay HLS playlist for tab 0+GET {{baseUrl}}/v2/interact/{{sessionId}}/replay/0 HTTP/1.1+Authorization: Bearer {{$dotenv TEST_API_KEY}}++### Create Browser Session without recording+POST {{baseUrl}}/v2/browser HTTP/1.1+Authorization: Bearer {{$dotenv TEST_API_KEY}}+content-type: application/json++{+ "recordSession": false+}+### Delete Browser Session β replace sessionId with actual idDELETE {{baseUrl}}/v2/browser/{{sessionId}} HTTP/1.1Authorization: Bearer {{$dotenv TEST_API_KEY}}diff --git a/apps/api/src/__tests__/snips/v2/browser-replay.test.ts b/apps/api/src/__tests__/snips/v2/browser-replay.test.tsnew file mode 100644index 000000000..f43a4b0d7--- /dev/null+++ b/apps/api/src/__tests__/snips/v2/browser-replay.test.ts@@ -0,0 +1,174 @@+import crypto from "crypto";+import { config } from "../../../config";+import {+ ALLOW_TEST_SUITE_WEBSITE,+ HAS_FIRE_ENGINE,+ TEST_PRODUCTION,+ TEST_SELF_HOST,+ TEST_SUITE_WEBSITE,+ itIf,+} from "../lib";+import {+ Identity,+ idmux,+ browserCreateRaw,+ browserExecuteRaw,+ browserDeleteRaw,+ browserReplayRaw,+ browserReplayPageRaw,+ scrapeTimeout,+} from "./lib";++const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));++describe("Interact session replay", () => {+ let identity: Identity;+ let otherIdentity: Identity;++ beforeAll(async () => {+ identity = await idmux({+ name: "browser-replay",+ concurrency: 20,+ credits: 1_000_000,+ });+ otherIdentity = await idmux({+ name: "browser-replay-other",+ concurrency: 10,+ credits: 1_000_000,+ });+ }, 10000 + scrapeTimeout);++ const canRunReplayHappyPath =+ ALLOW_TEST_SUITE_WEBSITE &&+ !!config.BROWSER_SERVICE_URL &&+ (TEST_PRODUCTION || HAS_FIRE_ENGINE);++ itIf(canRunReplayHappyPath)(+ "records a session and serves replay metadata + HLS playlist after destroy",+ async () => {+ let sessionId: string | null = null;++ try {+ const createResponse = await browserCreateRaw(+ { ttl: 120, activityTtl: 120 },+ identity,+ );+ expect(createResponse.statusCode).toBe(200);+ expect(createResponse.body.success).toBe(true);+ sessionId = createResponse.body.id as string;++ // Generate on-screen activity so the screencast has frames to record.+ const executeResponse = await browserExecuteRaw(+ sessionId,+ {+ language: "node",+ timeout: 60,+ code: `+ await page.goto("${TEST_SUITE_WEBSITE}?testId=${crypto.randomUUID()}");+ console.log("navigated");+ `,+ },+ identity,+ );+ expect(executeResponse.statusCode).toBe(200);+ expect(executeResponse.body.success).toBe(true);++ // Wait past a segment boundary (10s) so at least one segment uploads.+ await sleep(15_000);+ } finally {+ if (sessionId) {+ await browserDeleteRaw(sessionId, identity);+ }+ }++ // Replay must be available after the session is destroyed.+ let replayResponse = await browserReplayRaw(sessionId!, identity);+ for (let i = 0; i < 10 && replayResponse.statusCode === 404; i++) {+ await sleep(2000);+ replayResponse = await browserReplayRaw(sessionId!, identity);+ }++ expect(replayResponse.statusCode).toBe(200);+ expect(replayResponse.body.success).toBe(true);+ expect(replayResponse.body.pageCount).toBeGreaterThan(0);+ expect(Array.isArray(replayResponse.body.pages)).toBe(true);++ const page = replayResponse.body.pages[0];+ expect(typeof page.pageId).toBe("string");+ expect(page.url).toBe(+ `/v2/interact/${sessionId}/replay/${page.pageId}`,+ );+ expect(page.endTimeMs).toBeGreaterThan(page.startTimeMs);++ const playlistResponse = await browserReplayPageRaw(+ sessionId!,+ page.pageId,+ identity,+ );+ expect(playlistResponse.statusCode).toBe(200);+ expect(playlistResponse.headers["content-type"]).toContain(+ "application/vnd.apple.mpegurl",+ );+ const playlist = playlistResponse.text as string;+ expect(playlist).toContain("#EXTM3U");+ expect(playlist).toContain("#EXT-X-ENDLIST");+ expect(playlist).toContain("https://");+ },+ scrapeTimeout + 60_000,+ );++ itIf(!TEST_SELF_HOST)(+ "returns 404 when the session does not exist",+ async () => {+ const response = await browserReplayRaw(crypto.randomUUID(), identity);++ expect(response.statusCode).toBe(404);+ expect(response.body.success).toBe(false);+ expect(response.body.error).toBe("Browser session not found.");+ },+ );++ itIf(!TEST_SELF_HOST)(+ "returns 400 for an invalid pageId",+ async () => {+ const response = await browserReplayPageRaw(+ crypto.randomUUID(),+ "not-a-page",+ identity,+ );++ expect(response.statusCode).toBe(400);+ expect(response.body.success).toBe(false);+ expect(response.body.error).toBe("Invalid pageId.");+ },+ );++ itIf(canRunReplayHappyPath && !!config.IDMUX_URL)(+ "returns 403 when the session belongs to another team",+ async () => {+ if (identity.teamId === otherIdentity.teamId) {+ return;+ }++ let sessionId: string | null = null;+ try {+ const createResponse = await browserCreateRaw(+ { ttl: 60, activityTtl: 60 },+ identity,+ );+ expect(createResponse.statusCode).toBe(200);+ sessionId = createResponse.body.id as string;++ const response = await browserReplayRaw(sessionId, otherIdentity);+ expect(response.statusCode).toBe(403);+ expect(response.body.success).toBe(false);+ expect(response.body.error).toBe("Forbidden.");+ } finally {+ if (sessionId) {+ await browserDeleteRaw(sessionId, identity);+ }+ }+ },+ scrapeTimeout,+ );+});diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.tsindex 68fa667f3..9199a9698 100644--- a/apps/api/src/__tests__/snips/v2/lib.ts+++ b/apps/api/src/__tests__/snips/v2/lib.ts@@ -340,6 +340,71 @@ export async function scrapeStopInteractiveBrowserRaw(.send();}+// =========================================+// Interact (standalone browser sessions)+// =========================================++export async function browserCreateRaw(+ body: {+ ttl?: number;+ activityTtl?: number;+ recordSession?: boolean;+ },+ identity: Identity,+) {+ return await request(TEST_API_URL)+ .post("/v2/interact")+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .set("Content-Type", "application/json")+ .send(body);+}++export async function browserExecuteRaw(+ sessionId: string,+ body: {+ code: string;+ language?: "python" | "node" | "bash";+ timeout?: number;+ },+ identity: Identity,+) {+ return await request(TEST_API_URL)+ .post("/v2/interact/" + encodeURIComponent(sessionId) + "/execute")+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .set("Content-Type", "application/json")+ .send(body);+}++export async function browserDeleteRaw(sessionId: string, identity: Identity) {+ return await request(TEST_API_URL)+ .delete("/v2/interact/" + encodeURIComponent(sessionId))+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .send();+}++export async function browserReplayRaw(sessionId: string, identity: Identity) {+ return await request(TEST_API_URL)+ .get("/v2/interact/" + encodeURIComponent(sessionId) + "/replay")+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .send();+}++export async function browserReplayPageRaw(+ sessionId: string,+ pageId: string,+ identity: Identity,+) {+ return await request(TEST_API_URL)+ .get(+ "/v2/interact/" ++ encodeURIComponent(sessionId) ++ "/replay/" ++ encodeURIComponent(pageId),+ )+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .send();+}+// =========================================// Crawl API// =========================================diff --git a/apps/api/src/controllers/v2/browser-replay.ts b/apps/api/src/controllers/v2/browser-replay.tsnew file mode 100644index 000000000..458e454e0--- /dev/null+++ b/apps/api/src/controllers/v2/browser-replay.ts@@ -0,0 +1,193 @@+import { Response } from "express";+import { logger as _logger } from "../../lib/logger";+import { config } from "../../config";+import { getBrowserSession } from "../../lib/browser-sessions";+import {+ browserServiceRequest,+ browserServiceRequestText,+ BrowserServiceError,+} from "../../lib/scrape-interact/browser-service-client";+import { RequestWithAuth } from "./types";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++interface BrowserServiceRecordingPage {+ pageId: string;+ url: string;+ startTimeMs: number;+ endTimeMs: number;+}++interface BrowserServiceRecordingResponse {+ pages: BrowserServiceRecordingPage[];+ pageCount: number;+}++interface BrowserReplayResponse {+ success: boolean;+ pages?: Array<{+ pageId: string;+ /** Path (relative to the API origin) serving this page's HLS playlist. */+ url: string;+ /** First page URL recorded on this tab. */+ pageUrl: string;+ /** Milliseconds from session start, not Unix epoch. */+ startTimeMs: number;+ endTimeMs: number;+ }>;+ pageCount?: number;+ error?: string;+}++const PAGE_ID_RE = /^\d{1,3}$/;++// ---------------------------------------------------------------------------+// Shared session resolution+// ---------------------------------------------------------------------------++async function resolveReplaySession(+ req: RequestWithAuth<{ sessionId: string }, any, any>,+ res: Response,+): Promise<{ browserId: string } | null> {+ if (!config.BROWSER_SERVICE_URL) {+ res.status(503).json({+ success: false,+ error:+ "Browser feature is not configured (BROWSER_SERVICE_URL is missing).",+ });+ return null;+ }++ const session = await getBrowserSession(req.params.sessionId);++ if (!session) {+ res.status(404).json({+ success: false,+ error: "Browser session not found.",+ });+ return null;+ }++ if (session.team_id !== req.auth.team_id) {+ res.status(403).json({+ success: false,+ error: "Forbidden.",+ });+ return null;+ }++ // Note: destroyed sessions are intentionally allowed β replay is most+ // useful after the session has ended.+ return { browserId: session.browser_id };+}++// ---------------------------------------------------------------------------+// Controllers+// ---------------------------------------------------------------------------++/**+ * GET /v2/interact/:sessionId/replay+ *+ * Lists the recorded pages (tabs) of a session. Each page has its own HLS+ * playlist; timestamps are milliseconds from session start on a shared+ * timeline across tabs.+ */+export async function browserReplayController(+ req: RequestWithAuth<{ sessionId: string }, BrowserReplayResponse>,+ res: Response<BrowserReplayResponse>,+) {+ const logger = _logger.child({+ sessionId: req.params.sessionId,+ teamId: req.auth.team_id,+ module: "api/v2",+ method: "browserReplayController",+ });++ const resolved = await resolveReplaySession(req, res);+ if (!resolved) return;++ let recording: BrowserServiceRecordingResponse;+ try {+ recording = await browserServiceRequest<BrowserServiceRecordingResponse>(+ "GET",+ `/browsers/${resolved.browserId}/recording`,+ );+ } catch (err) {+ if (err instanceof BrowserServiceError && err.status === 404) {+ return res.status(404).json({+ success: false,+ error: "Replay not found.",+ });+ }+ logger.error("Failed to fetch recording metadata", { error: err });+ return res.status(502).json({+ success: false,+ error: "Failed to fetch session replay.",+ });+ }++ return res.status(200).json({+ success: true,+ pages: recording.pages.map(page => ({+ pageId: page.pageId,+ url: `/v2/interact/${req.params.sessionId}/replay/${page.pageId}`,+ pageUrl: page.url,+ startTimeMs: page.startTimeMs,+ endTimeMs: page.endTimeMs,+ })),+ pageCount: recording.pageCount,+ });+}++/**+ * GET /v2/interact/:sessionId/replay/:pageId+ *+ * Returns the HLS VOD playlist (.m3u8) for one recorded page. Segment URLs+ * inside the playlist are pre-signed and expire (~6h); re-request the+ * playlist to mint fresh ones. Hand the body to any HLS-capable player.+ */+export async function browserReplayPageController(+ req: RequestWithAuth<{ sessionId: string; pageId: string }, any>,+ res: Response,+) {+ const logger = _logger.child({+ sessionId: req.params.sessionId,+ teamId: req.auth.team_id,+ module: "api/v2",+ method: "browserReplayPageController",+ });++ if (!PAGE_ID_RE.test(req.params.pageId)) {+ return res.status(400).json({+ success: false,+ error: "Invalid pageId.",+ });+ }++ const resolved = await resolveReplaySession(req, res);+ if (!resolved) return;++ try {+ const { body } = await browserServiceRequestText(+ "GET",+ `/browsers/${resolved.browserId}/recording/${req.params.pageId}`,+ );+ res.setHeader("Content-Type", "application/vnd.apple.mpegurl");+ res.setHeader("Cache-Control", "no-store");+ return res.status(200).send(body);+ } catch (err) {+ if (err instanceof BrowserServiceError && err.status === 404) {+ return res.status(404).json({+ success: false,+ error: "Replay not found.",+ });+ }+ logger.error("Failed to fetch recording playlist", { error: err });+ return res.status(502).json({+ success: false,+ error: "Failed to fetch session replay.",+ });+ }+}diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.tsindex ae15531f5..745c0b934 100644--- a/apps/api/src/controllers/v2/browser.ts+++ b/apps/api/src/controllers/v2/browser.ts@@ -42,6 +42,7 @@ const browserCreateRequestSchema = z.object({ttl: z.number().min(30).max(3600).default(600),activityTtl: z.number().min(10).max(3600).default(300),streamWebView: z.boolean().default(true),+ recordSession: z.boolean().default(true),integration: integrationSchema.optional().transform(val => val || null),profile: z.object({@@ -212,7 +213,8 @@ export async function browserCreateController(req.body = browserCreateRequestSchema.parse(req.body);- const { ttl, activityTtl, streamWebView, profile, integration } = req.body;+ const { ttl, activityTtl, streamWebView, recordSession, profile, integration } =+ req.body;if (!config.BROWSER_SERVICE_URL) {return res.status(503).json({@@ -282,6 +284,7 @@ export async function browserCreateController("/browsers",{ttl,+ record: recordSession,...(activityTtl !== undefined ? { activityTtl } : {}),...(persistentStorage !== undefined ? { persistentStorage } : {}),},diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.tsindex eb9129b64..8638f9754 100644--- a/apps/api/src/controllers/v2/scrape-browser.ts+++ b/apps/api/src/controllers/v2/scrape-browser.ts@@ -99,6 +99,7 @@ type BrowserExecuteRequest = z.infer<typeof browserExecuteRequestSchema>;interface BrowserExecuteResponse {success: boolean;+ sessionId?: string;cdpUrl?: string;liveViewUrl?: string;interactiveLiveViewUrl?: string;@@ -370,6 +371,7 @@ export async function scrapeInteractController(return res.status(200).json({success: !hasError,+ sessionId: session.id,cdpUrl: session.cdp_url,liveViewUrl: session.cdp_path,interactiveLiveViewUrl: session.cdp_interactive_path,diff --git a/apps/api/src/lib/scrape-interact/browser-service-client.ts b/apps/api/src/lib/scrape-interact/browser-service-client.tsindex 371c0dca3..bd06c9c09 100644--- a/apps/api/src/lib/scrape-interact/browser-service-client.ts+++ b/apps/api/src/lib/scrape-interact/browser-service-client.ts@@ -82,3 +82,31 @@ export async function browserServiceRequest<T>(if (res.status === 204) return undefined as T;return res.json() as Promise<T>;}++/**+ * Call the browser service and return the raw response body as text+ * (used for HLS playlists). Throws `BrowserServiceError` on non-2xx.+ */+export async function browserServiceRequestText(+ method: string,+ path: string,+): Promise<{ body: string; contentType: string | null }> {+ const url = `${config.BROWSER_SERVICE_URL}${path}`;+ const res = await fetch(url, {+ method,+ headers: browserServiceHeaders(),+ });++ if (!res.ok) {+ const text = await res.text();+ throw new BrowserServiceError(+ res.status,+ `Browser service ${method} ${path} failed (${res.status}): ${text}`,+ );+ }++ return {+ body: await res.text(),+ contentType: res.headers.get("content-type"),+ };+}diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.tsindex f45bb0a68..2e02c923f 100644--- a/apps/api/src/routes/v2.ts+++ b/apps/api/src/routes/v2.ts@@ -59,6 +59,10 @@ import {browserListController,browserWebhookDestroyedController,} from "../controllers/v2/browser";+import {+ browserReplayController,+ browserReplayPageController,+} from "../controllers/v2/browser-replay";import { activityController } from "../controllers/v1/activity";import { supportProxyController } from "../controllers/v2/support-proxy";import { createResearchRouter } from "../controllers/v2/research-proxy";@@ -525,6 +529,18 @@ v2Router.post(wrap(browserExecuteController),);+v2Router.get(+ ["/browser/:sessionId/replay", "/interact/:sessionId/replay"],+ authMiddleware(RateLimiterMode.BrowserExecute),+ wrap(browserReplayController),+);++v2Router.get(+ ["/browser/:sessionId/replay/:pageId", "/interact/:sessionId/replay/:pageId"],+ authMiddleware(RateLimiterMode.BrowserExecute),+ wrap(browserReplayPageController),+);+v2Router.delete(["/browser/:sessionId", "/interact/:sessionId"],authMiddleware(RateLimiterMode.BrowserExecute),