firecrawl 1.29.3 → 3.0.2

package/dist/index.cjs

@@ -34,8 +34,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
-      name: "@mendable/firecrawl-js",
-      version: "1.29.3",
+      name: "firecrawl",
+      version: "3.0.2",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -51,12 +51,12 @@ var require_package = __commonJS({
         build: "tsup",
         "build-and-publish": "npm run build && npm publish --access public",
         "publish-beta": "npm run build && npm publish --access public --tag beta",
-        test: "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/v1/**/*.test.ts",
-        "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/v1/unit/*.test.ts"
+        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"
       },
       repository: {
         type: "git",
-        url: "git+https://github.com/mendableai/firecrawl.git"
+        url: "git+https://github.com/firecrawl/firecrawl.git"
       },
       author: "Mendable.ai",
       license: "MIT",
@@ -67,9 +67,9 @@ var require_package = __commonJS({
         "zod-to-json-schema": "^3.23.0"
       },
       bugs: {
-        url: "https://github.com/mendableai/firecrawl/issues"
+        url: "https://github.com/firecrawl/firecrawl/issues"
       },
-      homepage: "https://github.com/mendableai/firecrawl#readme",
+      homepage: "https://github.com/firecrawl/firecrawl#readme",
       devDependencies: {
         "@jest/globals": "^30.0.5",
         "@types/dotenv": "^8.2.0",
@@ -108,16 +108,915 @@ var require_package = __commonJS({
 });
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  CrawlWatcher: () => CrawlWatcher,
-  FirecrawlError: () => FirecrawlError,
-  default: () => FirecrawlApp
+var src_exports = {};
+__export(src_exports, {
+  Firecrawl: () => Firecrawl,
+  FirecrawlAppV1: () => FirecrawlApp,
+  FirecrawlClient: () => FirecrawlClient,
+  SdkError: () => SdkError,
+  default: () => src_default
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
+
+// src/v2/utils/httpClient.ts
 var import_axios = __toESM(require("axios"), 1);
+
+// src/v2/utils/getVersion.ts
+function getVersion() {
+  try {
+    if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
+      return process.env.npm_package_version;
+    }
+    const pkg = require_package();
+    return pkg?.version || "3.x.x";
+  } catch {
+    return "3.x.x";
+  }
+}
+
+// src/v2/utils/httpClient.ts
+var HttpClient = class {
+  instance;
+  apiKey;
+  apiUrl;
+  maxRetries;
+  backoffFactor;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.apiUrl = options.apiUrl.replace(/\/$/, "");
+    this.maxRetries = options.maxRetries ?? 3;
+    this.backoffFactor = options.backoffFactor ?? 0.5;
+    this.instance = import_axios.default.create({
+      baseURL: this.apiUrl,
+      timeout: options.timeoutMs ?? 6e4,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      transitional: { clarifyTimeoutError: true }
+    });
+  }
+  getApiUrl() {
+    return this.apiUrl;
+  }
+  getApiKey() {
+    return this.apiKey;
+  }
+  async request(config) {
+    const version = getVersion();
+    config.headers = {
+      ...config.headers || {}
+    };
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const cfg = { ...config };
+        if (cfg.method && ["post", "put", "patch"].includes(cfg.method.toLowerCase())) {
+          const data = cfg.data ?? {};
+          cfg.data = { ...data, origin: `js-sdk@${version}` };
+        }
+        const res = await this.instance.request(cfg);
+        if (res.status === 502 && attempt < this.maxRetries - 1) {
+          await this.sleep(this.backoffFactor * Math.pow(2, attempt));
+          continue;
+        }
+        return res;
+      } catch (err) {
+        lastError = err;
+        const status = err?.response?.status;
+        if (status === 502 && attempt < this.maxRetries - 1) {
+          await this.sleep(this.backoffFactor * Math.pow(2, attempt));
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastError ?? new Error("Unexpected HTTP client error");
+  }
+  sleep(seconds) {
+    return new Promise((r) => setTimeout(r, seconds * 1e3));
+  }
+  post(endpoint, body, headers) {
+    return this.request({ method: "post", url: endpoint, data: body, headers });
+  }
+  get(endpoint, headers) {
+    return this.request({ method: "get", url: endpoint, headers });
+  }
+  delete(endpoint, headers) {
+    return this.request({ method: "delete", url: endpoint, headers });
+  }
+  prepareHeaders(idempotencyKey) {
+    const headers = {};
+    if (idempotencyKey) headers["x-idempotency-key"] = idempotencyKey;
+    return headers;
+  }
+};
+
+// src/v2/types.ts
+var SdkError = class extends Error {
+  status;
+  code;
+  details;
+  constructor(message, status, code, details) {
+    super(message);
+    this.name = "FirecrawlSdkError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/v2/utils/validation.ts
+var import_zod_to_json_schema = __toESM(require("zod-to-json-schema"), 1);
+function ensureValidFormats(formats) {
+  if (!formats) return;
+  for (const fmt of formats) {
+    if (typeof fmt === "string") {
+      if (fmt === "json") {
+        throw new Error("json format must be an object with { type: 'json', prompt, schema }");
+      }
+      continue;
+    }
+    if (fmt.type === "json") {
+      const j = fmt;
+      if (!j.prompt && !j.schema) {
+        throw new Error("json format requires either 'prompt' or 'schema' (or both)");
+      }
+      const maybeSchema = j.schema;
+      const isZod = !!maybeSchema && (typeof maybeSchema.safeParse === "function" || typeof maybeSchema.parse === "function") && !!maybeSchema._def;
+      if (isZod) {
+        try {
+          j.schema = (0, import_zod_to_json_schema.default)(maybeSchema);
+        } catch {
+        }
+      }
+      continue;
+    }
+    if (fmt.type === "screenshot") {
+      const s = fmt;
+      if (s.quality != null && (typeof s.quality !== "number" || s.quality < 0)) {
+        throw new Error("screenshot.quality must be a non-negative number");
+      }
+    }
+  }
+}
+function ensureValidScrapeOptions(options) {
+  if (!options) return;
+  if (options.timeout != null && options.timeout <= 0) {
+    throw new Error("timeout must be positive");
+  }
+  if (options.waitFor != null && options.waitFor < 0) {
+    throw new Error("waitFor must be non-negative");
+  }
+  ensureValidFormats(options.formats);
+}
+
+// src/v2/utils/errorHandler.ts
+var import_axios2 = require("axios");
+function throwForBadResponse(resp, action) {
+  const status = resp.status;
+  const body = resp.data || {};
+  const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
+  throw new SdkError(msg, status, void 0, body?.details);
+}
+function normalizeAxiosError(err, action) {
+  const status = err.response?.status;
+  const body = err.response?.data;
+  const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
+  const code = body?.code || err.code;
+  throw new SdkError(message, status, code, body?.details ?? body);
+}
+
+// src/v2/methods/scrape.ts
+async function scrape(http, url, options) {
+  if (!url || !url.trim()) {
+    throw new Error("URL cannot be empty");
+  }
+  if (options) ensureValidScrapeOptions(options);
+  const payload = { url: url.trim() };
+  if (options) Object.assign(payload, options);
+  try {
+    const res = await http.post("/v2/scrape", payload);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "scrape");
+    }
+    return res.data.data || {};
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "scrape");
+    throw err;
+  }
+}
+
+// src/v2/methods/search.ts
+function prepareSearchPayload(req) {
+  if (!req.query || !req.query.trim()) throw new Error("Query cannot be empty");
+  if (req.limit != null && req.limit <= 0) throw new Error("limit must be positive");
+  if (req.timeout != null && req.timeout <= 0) throw new Error("timeout must be positive");
+  const payload = {
+    query: req.query
+  };
+  if (req.sources) payload.sources = req.sources;
+  if (req.limit != null) payload.limit = req.limit;
+  if (req.tbs != null) payload.tbs = req.tbs;
+  if (req.location != null) payload.location = req.location;
+  if (req.ignoreInvalidURLs != null) payload.ignoreInvalidURLs = req.ignoreInvalidURLs;
+  if (req.timeout != null) payload.timeout = req.timeout;
+  if (req.scrapeOptions) {
+    ensureValidScrapeOptions(req.scrapeOptions);
+    payload.scrapeOptions = req.scrapeOptions;
+  }
+  return payload;
+}
+async function search(http, request) {
+  const payload = prepareSearchPayload(request);
+  try {
+    const res = await http.post("/v2/search", payload);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "search");
+    }
+    const data = res.data.data || {};
+    const out = {};
+    for (const key of Object.keys(data)) {
+      const arr = data[key];
+      if (Array.isArray(arr)) {
+        const results = [];
+        for (const item of arr) {
+          if (item && typeof item === "object") {
+            if ("markdown" in item || "html" in item || "rawHtml" in item || "links" in item || "screenshot" in item || "changeTracking" in item || "summary" in item || "json" in item) {
+              results.push(item);
+            } else {
+              results.push({ url: item.url, title: item.title, description: item.description });
+            }
+          } else if (typeof item === "string") {
+            results.push({ url: item });
+          }
+        }
+        out[key] = results;
+      }
+    }
+    return out;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "search");
+    throw err;
+  }
+}
+
+// src/v2/methods/map.ts
+function prepareMapPayload(url, options) {
+  if (!url || !url.trim()) throw new Error("URL cannot be empty");
+  const payload = { url: url.trim() };
+  if (options) {
+    if (options.sitemap != null) payload.sitemap = options.sitemap;
+    if (options.search != null) payload.search = options.search;
+    if (options.includeSubdomains != null) payload.includeSubdomains = options.includeSubdomains;
+    if (options.limit != null) payload.limit = options.limit;
+    if (options.timeout != null) payload.timeout = options.timeout;
+  }
+  return payload;
+}
+async function map(http, url, options) {
+  const payload = prepareMapPayload(url, options);
+  try {
+    const res = await http.post("/v2/map", payload);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "map");
+    }
+    const linksIn = res.data.links || [];
+    const links = [];
+    for (const item of linksIn) {
+      if (typeof item === "string") links.push({ url: item });
+      else if (item && typeof item === "object") links.push({ url: item.url, title: item.title, description: item.description });
+    }
+    return { links };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "map");
+    throw err;
+  }
+}
+
+// src/v2/methods/crawl.ts
+function prepareCrawlPayload(request) {
+  if (!request.url || !request.url.trim()) throw new Error("URL cannot be empty");
+  const data = { url: request.url.trim() };
+  if (request.prompt) data.prompt = request.prompt;
+  if (request.excludePaths) data.excludePaths = request.excludePaths;
+  if (request.includePaths) data.includePaths = request.includePaths;
+  if (request.maxDiscoveryDepth != null) data.maxDiscoveryDepth = request.maxDiscoveryDepth;
+  if (request.sitemap != null) data.sitemap = request.sitemap;
+  if (request.ignoreQueryParameters != null) data.ignoreQueryParameters = request.ignoreQueryParameters;
+  if (request.limit != null) data.limit = request.limit;
+  if (request.crawlEntireDomain != null) data.crawlEntireDomain = request.crawlEntireDomain;
+  if (request.allowExternalLinks != null) data.allowExternalLinks = request.allowExternalLinks;
+  if (request.allowSubdomains != null) data.allowSubdomains = request.allowSubdomains;
+  if (request.delay != null) data.delay = request.delay;
+  if (request.maxConcurrency != null) data.maxConcurrency = request.maxConcurrency;
+  if (request.webhook != null) data.webhook = request.webhook;
+  if (request.scrapeOptions) {
+    ensureValidScrapeOptions(request.scrapeOptions);
+    data.scrapeOptions = request.scrapeOptions;
+  }
+  if (request.zeroDataRetention != null) data.zeroDataRetention = request.zeroDataRetention;
+  return data;
+}
+async function startCrawl(http, request) {
+  const payload = prepareCrawlPayload(request);
+  try {
+    const res = await http.post("/v2/crawl", payload);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "start crawl");
+    }
+    return { id: res.data.id, url: res.data.url };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "start crawl");
+    throw err;
+  }
+}
+async function getCrawlStatus(http, jobId) {
+  try {
+    const res = await http.get(`/v2/crawl/${jobId}`);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "get crawl status");
+    }
+    const body = res.data;
+    return {
+      status: body.status,
+      completed: body.completed ?? 0,
+      total: body.total ?? 0,
+      creditsUsed: body.creditsUsed,
+      expiresAt: body.expiresAt,
+      next: body.next ?? null,
+      data: body.data || []
+    };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get crawl status");
+    throw err;
+  }
+}
+async function cancelCrawl(http, jobId) {
+  try {
+    const res = await http.delete(`/v2/crawl/${jobId}`);
+    if (res.status !== 200) throwForBadResponse(res, "cancel crawl");
+    return res.data?.status === "cancelled";
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "cancel crawl");
+    throw err;
+  }
+}
+async function waitForCrawlCompletion(http, jobId, pollInterval = 2, timeout) {
+  const start = Date.now();
+  while (true) {
+    const status = await getCrawlStatus(http, jobId);
+    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    if (timeout != null && Date.now() - start > timeout * 1e3) {
+      throw new Error(`Crawl job ${jobId} did not complete within ${timeout} seconds`);
+    }
+    await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
+  }
+}
+async function crawl(http, request, pollInterval = 2, timeout) {
+  const started = await startCrawl(http, request);
+  return waitForCrawlCompletion(http, started.id, pollInterval, timeout);
+}
+async function getCrawlErrors(http, crawlId) {
+  try {
+    const res = await http.get(`/v2/crawl/${crawlId}/errors`);
+    if (res.status !== 200) throwForBadResponse(res, "get crawl errors");
+    const payload = res.data?.data ?? res.data;
+    return { errors: payload.errors || [], robotsBlocked: payload.robotsBlocked || [] };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get crawl errors");
+    throw err;
+  }
+}
+async function getActiveCrawls(http) {
+  try {
+    const res = await http.get(`/v2/crawl/active`);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get active crawls");
+    const crawlsIn = res.data?.crawls || [];
+    const crawls = crawlsIn.map((c) => ({ id: c.id, teamId: c.teamId ?? c.team_id, url: c.url, options: c.options ?? null }));
+    return { success: true, crawls };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get active crawls");
+    throw err;
+  }
+}
+async function crawlParamsPreview(http, url, prompt) {
+  if (!url || !url.trim()) throw new Error("URL cannot be empty");
+  if (!prompt || !prompt.trim()) throw new Error("Prompt cannot be empty");
+  try {
+    const res = await http.post("/v2/crawl/params-preview", { url: url.trim(), prompt });
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "crawl params preview");
+    const data = res.data.data || {};
+    if (res.data.warning) data.warning = res.data.warning;
+    return data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "crawl params preview");
+    throw err;
+  }
+}
+
+// src/v2/methods/batch.ts
+async function startBatchScrape(http, urls, {
+  options,
+  webhook,
+  appendToId,
+  ignoreInvalidURLs,
+  maxConcurrency,
+  zeroDataRetention,
+  integration,
+  idempotencyKey
+} = {}) {
+  if (!Array.isArray(urls) || urls.length === 0) throw new Error("URLs list cannot be empty");
+  const payload = { urls };
+  if (options) {
+    ensureValidScrapeOptions(options);
+    Object.assign(payload, options);
+  }
+  if (webhook != null) payload.webhook = webhook;
+  if (appendToId != null) payload.appendToId = appendToId;
+  if (ignoreInvalidURLs != null) payload.ignoreInvalidURLs = ignoreInvalidURLs;
+  if (maxConcurrency != null) payload.maxConcurrency = maxConcurrency;
+  if (zeroDataRetention != null) payload.zeroDataRetention = zeroDataRetention;
+  if (integration != null) payload.integration = integration;
+  try {
+    const headers = http.prepareHeaders(idempotencyKey);
+    const res = await http.post("/v2/batch/scrape", payload, headers);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "start batch scrape");
+    return { id: res.data.id, url: res.data.url, invalidURLs: res.data.invalidURLs || void 0 };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "start batch scrape");
+    throw err;
+  }
+}
+async function getBatchScrapeStatus(http, jobId) {
+  try {
+    const res = await http.get(`/v2/batch/scrape/${jobId}`);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get batch scrape status");
+    const body = res.data;
+    return {
+      status: body.status,
+      completed: body.completed ?? 0,
+      total: body.total ?? 0,
+      creditsUsed: body.creditsUsed,
+      expiresAt: body.expiresAt,
+      next: body.next ?? null,
+      data: body.data || []
+    };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get batch scrape status");
+    throw err;
+  }
+}
+async function cancelBatchScrape(http, jobId) {
+  try {
+    const res = await http.delete(`/v2/batch/scrape/${jobId}`);
+    if (res.status !== 200) throwForBadResponse(res, "cancel batch scrape");
+    return res.data?.status === "cancelled";
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "cancel batch scrape");
+    throw err;
+  }
+}
+async function getBatchScrapeErrors(http, jobId) {
+  try {
+    const res = await http.get(`/v2/batch/scrape/${jobId}/errors`);
+    if (res.status !== 200) throwForBadResponse(res, "get batch scrape errors");
+    const payload = res.data?.data ?? res.data;
+    return { errors: payload.errors || [], robotsBlocked: payload.robotsBlocked || [] };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get batch scrape errors");
+    throw err;
+  }
+}
+async function waitForBatchCompletion(http, jobId, pollInterval = 2, timeout) {
+  const start = Date.now();
+  while (true) {
+    const status = await getBatchScrapeStatus(http, jobId);
+    if (["completed", "failed", "cancelled"].includes(status.status)) return status;
+    if (timeout != null && Date.now() - start > timeout * 1e3) {
+      throw new Error(`Batch scrape job ${jobId} did not complete within ${timeout} seconds`);
+    }
+    await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
+  }
+}
+async function batchScrape(http, urls, opts = {}) {
+  const start = await startBatchScrape(http, urls, opts);
+  return waitForBatchCompletion(http, start.id, opts.pollInterval ?? 2, opts.timeout);
+}
+
+// src/v2/methods/extract.ts
+var import_zod_to_json_schema2 = require("zod-to-json-schema");
+function prepareExtractPayload(args) {
+  const body = {};
+  if (args.urls) body.urls = args.urls;
+  if (args.prompt != null) body.prompt = args.prompt;
+  if (args.schema != null) {
+    const s = args.schema;
+    const isZod = s && (typeof s.safeParse === "function" || typeof s.parse === "function") && s._def;
+    body.schema = isZod ? (0, import_zod_to_json_schema2.zodToJsonSchema)(s) : args.schema;
+  }
+  if (args.systemPrompt != null) body.systemPrompt = args.systemPrompt;
+  if (args.allowExternalLinks != null) body.allowExternalLinks = args.allowExternalLinks;
+  if (args.enableWebSearch != null) body.enableWebSearch = args.enableWebSearch;
+  if (args.showSources != null) body.showSources = args.showSources;
+  if (args.ignoreInvalidURLs != null) body.ignoreInvalidURLs = args.ignoreInvalidURLs;
+  if (args.scrapeOptions) {
+    ensureValidScrapeOptions(args.scrapeOptions);
+    body.scrapeOptions = args.scrapeOptions;
+  }
+  return body;
+}
+async function startExtract(http, args) {
+  const payload = prepareExtractPayload(args);
+  try {
+    const res = await http.post("/v2/extract", payload);
+    if (res.status !== 200) throwForBadResponse(res, "extract");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "extract");
+    throw err;
+  }
+}
+async function getExtractStatus(http, jobId) {
+  try {
+    const res = await http.get(`/v2/extract/${jobId}`);
+    if (res.status !== 200) throwForBadResponse(res, "extract status");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "extract status");
+    throw err;
+  }
+}
+async function waitExtract(http, jobId, pollInterval = 2, timeout) {
+  const start = Date.now();
+  while (true) {
+    const status = await getExtractStatus(http, jobId);
+    if (["completed", "failed", "cancelled"].includes(status.status || "")) return status;
+    if (timeout != null && Date.now() - start > timeout * 1e3) return status;
+    await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
+  }
+}
+async function extract(http, args) {
+  const started = await startExtract(http, args);
+  const jobId = started.id;
+  if (!jobId) return started;
+  return waitExtract(http, jobId, args.pollInterval ?? 2, args.timeout);
+}
+
+// src/v2/methods/usage.ts
+async function getConcurrency(http) {
+  try {
+    const res = await http.get("/v2/concurrency-check");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get concurrency");
+    const d = res.data.data || res.data;
+    return { concurrency: d.concurrency, maxConcurrency: d.maxConcurrency ?? d.max_concurrency };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get concurrency");
+    throw err;
+  }
+}
+async function getCreditUsage(http) {
+  try {
+    const res = await http.get("/v2/team/credit-usage");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage");
+    const d = res.data.data || res.data;
+    return { remainingCredits: d.remainingCredits ?? d.remaining_credits ?? 0 };
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage");
+    throw err;
+  }
+}
+async function getTokenUsage(http) {
+  try {
+    const res = await http.get("/v2/team/token-usage");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage");
+    return res.data.data || res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage");
+    throw err;
+  }
+}
+
+// src/v2/watcher.ts
+var import_events = require("events");
+var Watcher = class extends import_events.EventEmitter {
+  http;
+  jobId;
+  kind;
+  pollInterval;
+  timeout;
+  ws;
+  closed = false;
+  constructor(http, jobId, opts = {}) {
+    super();
+    this.http = http;
+    this.jobId = jobId;
+    this.kind = opts.kind ?? "crawl";
+    this.pollInterval = opts.pollInterval ?? 2;
+    this.timeout = opts.timeout;
+  }
+  buildWsUrl() {
+    const apiUrl = this.http.getApiUrl();
+    const wsBase = apiUrl.replace(/^http/, "ws");
+    const path = this.kind === "crawl" ? `/v2/crawl/${this.jobId}` : `/v2/batch/scrape/${this.jobId}`;
+    return `${wsBase}${path}`;
+  }
+  async start() {
+    try {
+      const url = this.buildWsUrl();
+      this.ws = new WebSocket(url, this.http.getApiKey());
+      this.attachWsHandlers(this.ws);
+    } catch {
+      this.pollLoop();
+    }
+  }
+  attachWsHandlers(ws) {
+    let startTs = Date.now();
+    const timeoutMs = this.timeout ? this.timeout * 1e3 : void 0;
+    ws.onmessage = (ev) => {
+      try {
+        const body = typeof ev.data === "string" ? JSON.parse(ev.data) : null;
+        if (!body) return;
+        const type = body.type;
+        if (type === "error") {
+          this.emit("error", { status: "failed", data: [], error: body.error, id: this.jobId });
+          return;
+        }
+        if (type === "catchup") {
+          const payload2 = body.data || {};
+          this.emitDocuments(payload2.data || []);
+          this.emitSnapshot(payload2);
+          return;
+        }
+        if (type === "document") {
+          const doc = body.data;
+          if (doc) this.emit("document", doc);
+          return;
+        }
+        if (type === "done") {
+          this.emit("done", { status: "completed", data: [], id: this.jobId });
+          this.close();
+          return;
+        }
+        const payload = body.data || body;
+        if (payload && payload.status) this.emitSnapshot(payload);
+      } catch {
+      }
+      if (timeoutMs && Date.now() - startTs > timeoutMs) this.close();
+    };
+    ws.onerror = () => {
+      this.emit("error", { status: "failed", data: [], error: "WebSocket error", id: this.jobId });
+      this.close();
+    };
+    ws.onclose = () => {
+      if (!this.closed) this.pollLoop();
+    };
+  }
+  emitDocuments(docs) {
+    for (const doc of docs) this.emit("document", { ...doc, id: this.jobId });
+  }
+  emitSnapshot(payload) {
+    const status = payload.status;
+    const data = payload.data || [];
+    const snap = this.kind === "crawl" ? {
+      status,
+      completed: payload.completed ?? 0,
+      total: payload.total ?? 0,
+      creditsUsed: payload.creditsUsed,
+      expiresAt: payload.expiresAt,
+      next: payload.next ?? null,
+      data
+    } : {
+      status,
+      completed: payload.completed ?? 0,
+      total: payload.total ?? 0,
+      creditsUsed: payload.creditsUsed,
+      expiresAt: payload.expiresAt,
+      next: payload.next ?? null,
+      data
+    };
+    this.emit("snapshot", snap);
+    if (["completed", "failed", "cancelled"].includes(status)) {
+      this.emit("done", { status, data, id: this.jobId });
+      this.close();
+    }
+  }
+  async pollLoop() {
+    const startTs = Date.now();
+    const timeoutMs = this.timeout ? this.timeout * 1e3 : void 0;
+    while (!this.closed) {
+      try {
+        const snap = this.kind === "crawl" ? await getCrawlStatus(this.http, this.jobId) : await getBatchScrapeStatus(this.http, this.jobId);
+        this.emit("snapshot", snap);
+        if (["completed", "failed", "cancelled"].includes(snap.status)) {
+          this.emit("done", { status: snap.status, data: snap.data, id: this.jobId });
+          this.close();
+          break;
+        }
+      } catch {
+      }
+      if (timeoutMs && Date.now() - startTs > timeoutMs) break;
+      await new Promise((r) => setTimeout(r, Math.max(1e3, this.pollInterval * 1e3)));
+    }
+  }
+  close() {
+    this.closed = true;
+    if (this.ws && this.ws.close) this.ws.close();
+  }
+};
+
+// src/v2/client.ts
+var FirecrawlClient = class {
+  http;
+  /**
+   * Create a v2 client.
+   * @param options Transport configuration (API key, base URL, timeouts, retries).
+   */
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "";
+    const apiUrl = (options.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
+    if (!apiKey) {
+      throw new Error("API key is required. Set FIRECRAWL_API_KEY env or pass apiKey.");
+    }
+    this.http = new HttpClient({
+      apiKey,
+      apiUrl,
+      timeoutMs: options.timeoutMs,
+      maxRetries: options.maxRetries,
+      backoffFactor: options.backoffFactor
+    });
+  }
+  async scrape(url, options) {
+    return scrape(this.http, url, options);
+  }
+  // Search
+  /**
+   * Search the web and optionally scrape each result.
+   * @param query Search query string.
+   * @param req Additional search options (sources, limit, scrapeOptions, etc.).
+   * @returns Structured search results.
+   */
+  async search(query, req = {}) {
+    return search(this.http, { query, ...req });
+  }
+  // Map
+  /**
+   * Map a site to discover URLs (sitemap-aware).
+   * @param url Root URL to map.
+   * @param options Mapping options (sitemap mode, includeSubdomains, limit, timeout).
+   * @returns Discovered links.
+   */
+  async map(url, options) {
+    return map(this.http, url, options);
+  }
+  // Crawl
+  /**
+   * Start a crawl job (async).
+   * @param url Root URL to crawl.
+   * @param req Crawl configuration (paths, limits, scrapeOptions, webhook, etc.).
+   * @returns Job id and url.
+   */
+  async startCrawl(url, req = {}) {
+    return startCrawl(this.http, { url, ...req });
+  }
+  /**
+   * Get the status and partial data of a crawl job.
+   * @param jobId Crawl job id.
+   */
+  async getCrawlStatus(jobId) {
+    return getCrawlStatus(this.http, jobId);
+  }
+  /**
+   * Cancel a crawl job.
+   * @param jobId Crawl job id.
+   * @returns True if cancelled.
+   */
+  async cancelCrawl(jobId) {
+    return cancelCrawl(this.http, jobId);
+  }
+  /**
+   * Convenience waiter: start a crawl and poll until it finishes.
+   * @param url Root URL to crawl.
+   * @param req Crawl configuration plus waiter controls (pollInterval, timeout seconds).
+   * @returns Final job snapshot.
+   */
+  async crawl(url, req = {}) {
+    return crawl(this.http, { url, ...req }, req.pollInterval, req.timeout);
+  }
+  /**
+   * Retrieve crawl errors and robots.txt blocks.
+   * @param crawlId Crawl job id.
+   */
+  async getCrawlErrors(crawlId) {
+    return getCrawlErrors(this.http, crawlId);
+  }
+  /**
+   * List active crawls for the authenticated team.
+   */
+  async getActiveCrawls() {
+    return getActiveCrawls(this.http);
+  }
+  /**
+   * Preview normalized crawl parameters produced by a natural-language prompt.
+   * @param url Root URL.
+   * @param prompt Natural-language instruction.
+   */
+  async crawlParamsPreview(url, prompt) {
+    return crawlParamsPreview(this.http, url, prompt);
+  }
+  // Batch
+  /**
+   * Start a batch scrape job for multiple URLs (async).
+   * @param urls URLs to scrape.
+   * @param opts Batch options (scrape options, webhook, concurrency, idempotency key, etc.).
+   * @returns Job id and url.
+   */
+  async startBatchScrape(urls, opts) {
+    return startBatchScrape(this.http, urls, opts);
+  }
+  /**
+   * Get the status and partial data of a batch scrape job.
+   * @param jobId Batch job id.
+   */
+  async getBatchScrapeStatus(jobId) {
+    return getBatchScrapeStatus(this.http, jobId);
+  }
+  /**
+   * Retrieve batch scrape errors and robots.txt blocks.
+   * @param jobId Batch job id.
+   */
+  async getBatchScrapeErrors(jobId) {
+    return getBatchScrapeErrors(this.http, jobId);
+  }
+  /**
+   * Cancel a batch scrape job.
+   * @param jobId Batch job id.
+   * @returns True if cancelled.
+   */
+  async cancelBatchScrape(jobId) {
+    return cancelBatchScrape(this.http, jobId);
+  }
+  /**
+   * Convenience waiter: start a batch scrape and poll until it finishes.
+   * @param urls URLs to scrape.
+   * @param opts Batch options plus waiter controls (pollInterval, timeout seconds).
+   * @returns Final job snapshot.
+   */
+  async batchScrape(urls, opts) {
+    return batchScrape(this.http, urls, opts);
+  }
+  // Extract
+  /**
+   * Start an extract job (async).
+   * @param args Extraction request (urls, schema or prompt, flags).
+   * @returns Job id or processing state.
+   */
+  async startExtract(args) {
+    return startExtract(this.http, args);
+  }
+  /**
+   * Get extract job status/data.
+   * @param jobId Extract job id.
+   */
+  async getExtractStatus(jobId) {
+    return getExtractStatus(this.http, jobId);
+  }
+  /**
+   * Convenience waiter: start an extract and poll until it finishes.
+   * @param args Extraction request plus waiter controls (pollInterval, timeout seconds).
+   * @returns Final extract response.
+   */
+  async extract(args) {
+    return extract(this.http, args);
+  }
+  // Usage
+  /** Current concurrency usage. */
+  async getConcurrency() {
+    return getConcurrency(this.http);
+  }
+  /** Current credit usage. */
+  async getCreditUsage() {
+    return getCreditUsage(this.http);
+  }
+  /** Recent token usage. */
+  async getTokenUsage() {
+    return getTokenUsage(this.http);
+  }
+  // Watcher
+  /**
+   * Create a watcher for a crawl or batch job. Emits: `document`, `snapshot`, `done`, `error`.
+   * @param jobId Job id.
+   * @param opts Watcher options (kind, pollInterval, timeout seconds).
+   */
+  watcher(jobId, opts = {}) {
+    return new Watcher(this.http, jobId, opts);
+  }
+};
+
+// src/v1/index.ts
+var import_axios3 = __toESM(require("axios"), 1);
 var zt = require("zod");
-var import_zod_to_json_schema = require("zod-to-json-schema");
+var import_zod_to_json_schema3 = require("zod-to-json-schema");
 
 // node_modules/typescript-event-target/dist/index.mjs
 var e = class extends EventTarget {
@@ -126,7 +1025,7 @@ var e = class extends EventTarget {
   }
 };
 
-// src/index.ts
+// src/v1/index.ts
 var FirecrawlError = class extends Error {
   statusCode;
   details;
@@ -145,10 +1044,16 @@ var FirecrawlApp = class {
   }
   async getVersion() {
     try {
+      if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
+        return process.env.npm_package_version;
+      }
       const packageJson = await Promise.resolve().then(() => __toESM(require_package(), 1));
       return packageJson.default.version;
     } catch (error) {
-      console.error("Error getting version:", error);
+      const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
+      if (!isTest) {
+        console.error("Error getting version:", error);
+      }
       return "1.25.1";
     }
   }
@@ -183,7 +1088,7 @@ var FirecrawlApp = class {
     if (jsonData?.extract?.schema) {
       let schema = jsonData.extract.schema;
       try {
-        schema = (0, import_zod_to_json_schema.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -197,7 +1102,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = (0, import_zod_to_json_schema.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -209,7 +1114,7 @@ var FirecrawlApp = class {
       };
     }
     try {
-      const response = await import_axios.default.post(
+      const response = await import_axios3.default.post(
         this.apiUrl + `/v1/scrape`,
         jsonData,
         { headers, timeout: params?.timeout !== void 0 ? params.timeout + 5e3 : void 0 }
@@ -260,7 +1165,7 @@ var FirecrawlApp = class {
     if (jsonData?.scrapeOptions?.extract?.schema) {
       let schema = jsonData.scrapeOptions.extract.schema;
       try {
-        schema = (0, import_zod_to_json_schema.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -481,9 +1386,9 @@ var FirecrawlApp = class {
    * @returns A CrawlWatcher instance to monitor the crawl job.
    */
   async crawlUrlAndWatch(url, params, idempotencyKey) {
-    const crawl = await this.asyncCrawlUrl(url, params, idempotencyKey);
-    if (crawl.success && crawl.id) {
-      const id = crawl.id;
+    const crawl2 = await this.asyncCrawlUrl(url, params, idempotencyKey);
+    if (crawl2.success && crawl2.id) {
+      const id = crawl2.id;
       return new CrawlWatcher(id, this);
     }
     throw new FirecrawlError("Crawl job failed to start", 400);
@@ -529,7 +1434,7 @@ var FirecrawlApp = class {
     if (jsonData?.extract?.schema) {
       let schema = jsonData.extract.schema;
       try {
-        schema = (0, import_zod_to_json_schema.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -543,7 +1448,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = (0, import_zod_to_json_schema.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -606,9 +1511,9 @@ var FirecrawlApp = class {
    * @returns A CrawlWatcher instance to monitor the crawl job.
    */
   async batchScrapeUrlsAndWatch(urls, params, idempotencyKey, webhook, ignoreInvalidURLs) {
-    const crawl = await this.asyncBatchScrapeUrls(urls, params, idempotencyKey, webhook, ignoreInvalidURLs);
-    if (crawl.success && crawl.id) {
-      const id = crawl.id;
+    const crawl2 = await this.asyncBatchScrapeUrls(urls, params, idempotencyKey, webhook, ignoreInvalidURLs);
+    if (crawl2.success && crawl2.id) {
+      const id = crawl2.id;
       return new CrawlWatcher(id, this);
     }
     throw new FirecrawlError("Batch scrape job failed to start", 400);
@@ -722,7 +1627,7 @@ var FirecrawlApp = class {
         jsonSchema = void 0;
       } else {
         try {
-          jsonSchema = (0, import_zod_to_json_schema.zodToJsonSchema)(params.schema);
+          jsonSchema = (0, import_zod_to_json_schema3.zodToJsonSchema)(params.schema);
         } catch (_) {
           jsonSchema = params.schema;
         }
@@ -786,7 +1691,7 @@ var FirecrawlApp = class {
         jsonSchema = void 0;
       } else {
         try {
-          jsonSchema = (0, import_zod_to_json_schema.zodToJsonSchema)(params.schema);
+          jsonSchema = (0, import_zod_to_json_schema3.zodToJsonSchema)(params.schema);
         } catch (_) {
           jsonSchema = params.schema;
         }
@@ -850,7 +1755,7 @@ var FirecrawlApp = class {
    * @returns The response from the POST request.
    */
   postRequest(url, data, headers) {
-    return import_axios.default.post(url, data, { headers, timeout: data?.timeout ? data.timeout + 5e3 : void 0 });
+    return import_axios3.default.post(url, data, { headers, timeout: data?.timeout ? data.timeout + 5e3 : void 0 });
   }
   /**
    * Sends a GET request to the specified URL.
@@ -860,9 +1765,9 @@ var FirecrawlApp = class {
    */
   async getRequest(url, headers) {
     try {
-      return await import_axios.default.get(url, { headers });
+      return await import_axios3.default.get(url, { headers });
     } catch (error) {
-      if (error instanceof import_axios.AxiosError && error.response) {
+      if (error instanceof import_axios3.AxiosError && error.response) {
         return error.response;
       } else {
         throw error;
@@ -877,9 +1782,9 @@ var FirecrawlApp = class {
    */
   async deleteRequest(url, headers) {
     try {
-      return await import_axios.default.delete(url, { headers });
+      return await import_axios3.default.delete(url, { headers });
     } catch (error) {
-      if (error instanceof import_axios.AxiosError && error.response) {
+      if (error instanceof import_axios3.AxiosError && error.response) {
         return error.response;
       } else {
         throw error;
@@ -958,7 +1863,7 @@ var FirecrawlApp = class {
    * @returns True if the error should be retried
    */
   isRetryableError(error) {
-    if (error instanceof import_axios.AxiosError) {
+    if (error instanceof import_axios3.AxiosError) {
       if (!error.response) {
         const code = error.code;
         const message = error.message?.toLowerCase() || "";
@@ -1077,7 +1982,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = (0, import_zod_to_json_schema.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1432,8 +2337,28 @@ var CrawlWatcher = class extends e {
     this.ws.close();
   }
 };
+
+// src/index.ts
+var Firecrawl = class extends FirecrawlClient {
+  /** Feature‑frozen v1 client (lazy). */
+  _v1;
+  _v1Opts;
+  /** @param opts API credentials and base URL. */
+  constructor(opts = {}) {
+    super(opts);
+    this._v1Opts = opts;
+  }
+  /** Access the legacy v1 client (instantiated on first access). */
+  get v1() {
+    if (!this._v1) this._v1 = new FirecrawlApp(this._v1Opts);
+    return this._v1;
+  }
+};
+var src_default = Firecrawl;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  CrawlWatcher,
-  FirecrawlError
+  Firecrawl,
+  FirecrawlAppV1,
+  FirecrawlClient,
+  SdkError
 });